SmartRoutes MCP Server

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.

Overview

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.

Available Tools

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.

Read-only mode

Those annotations are hints your client chooses to honour. To make writes impossible, add one header:

x-access-scope: read-only

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.

{
  "mcpServers": {
    "smartroutes-readonly": {
      "type": "http",
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>",
        "x-access-scope": "read-only"
      }
    }
  }
}

Register both entries side by side and pick per conversation. Any client that lets you set request headers supports this.

Setup

1. Get your API key

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.

2. Choose how to send it

Two headers are accepted and they are interchangeable — the value is the same API key either way:

A few things worth knowing:

• The scheme word is case-insensitive — 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.
• Send one of the two. If both are present with different values the request is rejected rather than one being picked, because guessing could point the assistant at the wrong account. Sending both with the same value is fine.

3. Connect your AI tool

Ready-to-copy config files for every client live in examples/ — drop in your key and go.

Quick start (Claude Code)

This repo includes a pre-configured .mcp.json. Just replace <your-api-key>:

{
  "mcpServers": {
    "smartroutes": {
      "type": "http",
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

Claude Code auto-discovers this file when you open the project.

Claude Desktop

Add a Custom Connector for SmartRoutes by going to: Settings → Connectors → Add custom connector

Here you can add the following details:

• Name: SmartRoutes (or whatever you like)
• URL: https://mcp.smartroutes.io/mcp

Add your authentication header under Advanced settings / Request headers in that same dialog:

• Key: x-access-key
• Value: your actual API key

Alternatively, you can add the following to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "smartroutes": {
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

Mistral Studio

Register SmartRoutes as a Connector:

• URL: https://mcp.smartroutes.io/mcp
• Header name: Authorization
• Header value: Bearer <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.

Cursor

In Cursor settings, add an MCP server:

• Name: smartroutes
• Type: Streamable HTTP
• URL: https://mcp.smartroutes.io/mcp
• Headers: x-access-key: <your-api-key>

Windsurf

Add to your Windsurf MCP config (mcp_config.json):

{
  "mcpServers": {
    "smartroutes": {
      "serverUrl": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

Any MCP Client (generic)

The server uses Streamable HTTP transport. Either header works:

POST https://mcp.smartroutes.io/mcp
Authorization: Bearer <your-api-key>

POST https://mcp.smartroutes.io/mcp
x-access-key: <your-api-key>

Any MCP client that speaks Streamable HTTP can connect. Legacy SSE clients are handled automatically.

4. Local development

Against a locally-running server the endpoint is (use whatever port your local app listens on):

http://localhost:3000/mcp-api

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.

Example Conversations

Once connected, you can ask your assistant things like:

• "What orders for tomorrow aren't on a route yet?"
• "Show me available vehicles and their shifts."
• "Can we fit a delivery to 12 Main St between 2–4pm on Friday?"
• "Optimise tomorrow's routes for all open orders — draft only, don't dispatch yet."
• "What's the status of that optimisation?"
• "Show me the plan for 2026-07-01 and the stops on route 3."
• "Add a 10 kg delivery for ACME at 5 King St."

API Key Management

Your MCP key is your SmartRoutes API key.

Troubleshooting

401 UNAUTHORIZED

The server didn't get a usable key. The description in the response body tells you which case you hit:

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.

Error shape

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:

{
  "name": "UNAUTHORIZED",
  "statusCode": 401,
  "description": "…",
  "details": {}
}

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.

Security

• Authentication: your API key, sent as either Authorization: Bearer <key> or the x-access-key header. Basic, Digest and other schemes are rejected.
• Depot isolation: every key is scoped to a single depot, and all data is filtered by depot.
• Rate limiting: each tool has its own per-key rate limit (shared with the REST API's limits).
• Write confirmation: write tools (add_order, optimise_plan_for_date) instruct the assistant to explain and confirm before running — especially auto-dispatch.
• Shared connectors: a connector registered at workspace or organisation visibility shares one API key across everyone who can see it, and our audit log records the key rather than the individual user. Register it personally if you need per-person attribution.

How it works

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:

1. list_orders / list_vehicles — see what's available
2. check_booking_availability — confirm a slot (optional)
3. add_order — enter new work
4. optimise_plan_for_date — build the plan (confirm before auto-dispatch)
5. get_optimisation_status — poll until it finishes
6. get_plan / get_route — read the result