Skip to main content

​
Get connected in 2 minutes

This guide gets you from zero to asking your AI assistant questions about your fleet data. The whole process takes about 2 minutes.

​
Prerequisites

  • A Bodha Route Planner account on the Pro or Enterprise plan
  • An AI assistant that supports MCP (Claude Desktop, Cursor, Windsurf, or any MCP-compatible client)

​
Step 1: Generate an API key

1

Open API key settings

Log in to Bodha Route Planner and go to Settings → API Keys (or Integrations → MCP).
2

Create a new key

Click Create Key.
3

Name your key

Give it a descriptive name — for example, “Claude Desktop” or “Cursor IDE”. This helps you identify which key is used where if you create multiple keys later.
4

Choose scopes

Select a scope preset:
  • Read-only (recommended) — Grants access to routes, stops, drivers, orders, analytics, and depots. This is everything you need for conversational queries.
  • Custom — Pick individual scopes if you want to limit access further.
5

Copy the key

Click Create. Your key appears once — copy it immediately. It cannot be retrieved later.The key looks like this:
Save your key securely. Bodha Route Planner stores only a hashed version. If you lose the key, you’ll need to create a new one.

​
Step 2: Add the config to your AI assistant

Every MCP-compatible AI assistant uses the same connection format. Copy this JSON and paste it into your assistant’s MCP configuration file:
Replace bdk_live_YOUR_KEY_HERE with the actual key you copied in Step 1.
Where does this JSON go? Each AI assistant has its own config file. See the dedicated setup guides for exact locations:

​
Step 3: Test the connection

Open your AI assistant and type:
“Show me today’s routes”
If everything is configured correctly, the assistant will:
  1. Discover the Bodha Route Planner MCP tools
  2. Call list_routes with today’s date
  3. Return your route data in plain language
You should see something like:
“You have 5 routes today with 142 total stops. 3 routes are in progress, 2 are dispatched and waiting to start. Your fleet completion rate so far is 67%.”

​
Troubleshooting

Check your config file:
  1. Make sure the JSON is valid (no trailing commas, no missing quotes)
  2. Verify the URL is exactly https://mcp.bodha.run/mcp
  3. Confirm the Authorization header starts with Bearer (note the space)
  4. Restart your AI assistant after saving the config
Still not working? Try generating a new API key and updating the config.
Your API key may be invalid or revoked.
  1. Go to Settings → API Keys in Bodha Route Planner
  2. Check that the key is listed and its status is Active
  3. If it’s revoked or you’re unsure, create a new key and update your config
The key doesn’t have the required scope for that tool.
  1. Go to Settings → API Keys
  2. Check the scopes assigned to your key
  3. If you need more access, create a new key with Read-only preset (all scopes)
This is normal. The MCP server runs on serverless infrastructure, so the first request after a period of inactivity takes a few seconds to “warm up” (cold start). Subsequent requests in the same session are much faster.
The MCP server allows 60 read calls per minute per key, with a hard limit of 10 requests per second. Normal conversational use rarely hits this. If you do hit it, wait a minute and try again.

​
What’s next?

Explore all 14 tools

See every tool with parameters, return fields, and example questions.

Scopes & security

Understand how scopes, encryption, and audit logging protect your data.