Smartroutes MCP server

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; addorder and optimiseplanfordate are marked as writes, and optimiseplanfor_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. addorder and optimiseplanfordate 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.

Shortened. The full README is on GitHub.