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

Tool	Type	Description
list_orders	Read	Orders for the depot (filter by date/status; 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 for a date
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

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.

Action	Description
Use	The same x-access-key as the REST API; scoped to one depot.
Disable	Disabling a key in your SmartRoutes account immediately blocks both MCP and REST access.

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