The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Smartroutes listing page.
Expose your SmartRoutes route-optimisation and dispatch tools to AI assistants like Claude Desktop, Claude Code, Cursor, Windsurf, and any other Model Context Protocol client — working against your live data.
The MCP server connects an AI tool to your live SmartRoutes account. Ask your AI Assistant which orders are still unscheduled, review a route plan, or kick off an optimisation — all in chat, against your real data.
It exposes the same operations as the SmartRoutes REST API, shaped as clean tools an agent can call directly. Everything is scoped to a single account by your API key.
| Tool | Type | Description |
|---|---|---|
list_orders | Read | Orders for the depot (filter by status, customer, order number, or last-updated time; paginated) |
get_order | Read | Full detail for a single order |
add_order | Write | Create a new order (pickup, delivery, or shipment) |
check_booking_availability | Read | Whether a time window + address can be served |
optimise_plan_for_date | Write | Trigger route optimisation for a date |
get_optimisation_status | Read | Poll an optimisation job until it finishes |
get_plan | Read | Plan-level totals and route summary, by plan id |
get_route | Read | Per-stop detail for a single route |
list_vehicles | Read | Fleet vehicles with shifts, capacities, and skills |
get_vehicle | Read | Full detail for a single vehicle |
list_customers | Read | Customers for the depot |
Every tool is annotated so your AI client can tell reads from writes. The nine read tools are marked read-only; add_order and optimise_plan_for_date are marked as writes, and optimise_plan_for_date is additionally marked destructive because auto-dispatch publishes the plan to drivers and notifies customers. Clients that gate destructive calls will ask you to confirm before running it.
Those annotations are hints your client chooses to honour. To make writes impossible, add one header:
The server then exposes only the nine read tools. add_order and optimise_plan_for_date are absent from the tool list entirely and cannot be called, so there is nothing for an assistant to invoke by accident — useful while testing, or for people who should only ever look things up.
Omit the header for the full tool set. Any other value is rejected with a 400, rather than being ignored, so a typo can never quietly restore write access.
Register both entries side by side and pick per conversation. Any client that lets you set request headers supports this.
The MCP server uses your existing SmartRoutes API key — the same one you already use for the REST API. There is no separate MCP credential, no sign-in flow, and no token that expires or needs refreshing.
To generate an API Key, login to your SmartRoutes account and go to Settings > Integrations > SmartRoutes Open API and click on the Generate API Key button.
Treat the key as a secret; it grants access to your account's data.
Two headers are accepted and they are interchangeable — the value is the same API key either way:
| Header | When to use it |
|---|---|
Authorization: Bearer <your-api-key> | Works everywhere. Use this on hosted platforms whose only credential field is Authorization — Mistral Studio and most connector directories. |
x-access-key: <your-api-key> | Equally valid and unchanged. Use it wherever you can name the header yourself: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, your own scripts. |
A few things worth knowing:
Bearer, bearer and BEARER all work. The key itself is case-sensitive, so copy it exactly.Basic and Digest are not supported. If the tool you're configuring only offers a username/password style credential, get in touch rather than base64-encoding the key yourself — it will be rejected.Ready-to-copy config files for every client live in
examples/— drop in your key and go.
This repo includes a pre-configured .mcp.json. Just replace <your-api-key>:
Claude Code auto-discovers this file when you open the project.
Add a Custom Connector for SmartRoutes by going to: Settings → Connectors → Add custom connector
Here you can add the following details:
Add your authentication header under Advanced settings / Request headers in that same dialog:
Alternatively, you can add the following to your Claude Desktop config (claude_desktop_config.json):
Register SmartRoutes as a Connector:
https://mcp.smartroutes.io/mcpAuthorizationBearer <your-api-key>Mistral's Connectors Debugger lets you validate a server before registering it, and it asks for the credential as an Authorization header — which is exactly what the Bearer form above is for. The Debugger is in public preview, so field labels may move; the URL and the header value are what matter.
In Cursor settings, add an MCP server:
https://mcp.smartroutes.io/mcpx-access-key: <your-api-key>Add to your Windsurf MCP config (mcp_config.json):
The server uses Streamable HTTP transport. Either header works:
Any MCP client that speaks Streamable HTTP can connect. Legacy SSE clients are handled automatically.
Against a locally-running server the endpoint is (use whatever port your local app listens on):
Note the path is /mcp-api locally — the shorter /mcp on mcp.smartroutes.io is a public alias for the same endpoint. Both headers work locally exactly as they do in production.
Once connected, you can ask your assistant things like:
Your MCP key is your SmartRoutes API key.
| Action | Description |
|---|---|
| Use | The same key as the REST API, sent as either Authorization: Bearer or x-access-key; scoped to one depot. |
| Disable | Disabling a key in your SmartRoutes account immediately blocks both MCP and REST access. |
401 UNAUTHORIZEDThe server didn't get a usable key. The description in the response body tells you which case you hit:
| Description | What to do |
|---|---|
No API key provided… | Neither header reached the server. On hosted platforms, check the header was actually saved onto the connector rather than just typed into the form. |
Unsupported Authorization scheme… | You sent Basic, Digest or something else. Only Bearer is accepted. |
Authorization header has no credential after the scheme | The value is Bearer with nothing after it. |
Authorization header must carry exactly one credential | Two credentials ended up in one header value. |
Conflicting credentials… | Both headers were sent with different values. Remove one. |
Invalid API Key provided | The key arrived but doesn't match an account. Re-copy it from Settings > Integrations — a truncated paste is the usual cause. |
Attempting to use disabled API key | The key was disabled in your SmartRoutes account. Generate a new one. |
API Key not authorized for expired trial account | The account's trial has ended. |
Every 401 also carries a WWW-Authenticate: Bearer response header. That is just the standard way of saying "a Bearer token is expected here" — it does not mean the server uses OAuth. There is no sign-in flow, no authorisation server to discover, and no /.well-known/ metadata to fetch. The static API key is the whole mechanism. If your client tries to start an OAuth flow after seeing that header, configure it with a static header credential instead.
Errors use the same envelope as the REST API, not a JSON-RPC error object — authentication is checked before the JSON-RPC layer is reached:
Rate limits are the exception you're most likely to see mid-conversation: those come back as an MCP tool result with name: "FORBIDDEN" and details.retry_after_seconds, so the assistant can back off and retry rather than dropping the connection.
Authorization: Bearer <key> or the x-access-key header. Basic, Digest and other schemes are rejected.add_order, optimise_plan_for_date) instruct the assistant to explain and confirm before running — especially auto-dispatch.The MCP server runs the same engine as the SmartRoutes REST API — each tool calls the same underlying service, so MCP and the API always agree on behaviour and data. Transport is Streamable HTTP; authentication is your API key.
A typical "plan tomorrow's routes" flow:
list_orders / list_vehicles — see what's availablecheck_booking_availability — confirm a slot (optional)add_order — enter new workoptimise_plan_for_date — build the plan (confirm before auto-dispatch)get_optimisation_status — poll until it finishesget_plan / get_route — read the result