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.

Related MCP server: dSIPRouter MCP Server

Available Tools

Write tools come with a confirmation step. The assistant explains what it's about to do and waits for your approval — especially optimise_plan_for_date with auto-dispatch, which publishes the plan to drivers and notifies customers.

Setup

1. Get your API key

The MCP server uses your existing SmartRoutes API key — the same x-access-key you already use for the REST API.

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. 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>"
      }
    }
  }
}

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:

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.

3. Local development

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

http://localhost:3000/mcp-api

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.

Security

• Authentication: API key in the x-access-key header.

• 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.

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