Smartroutes

What smartroutes does

The smartroutes MCP server exposes SmartRoutes route-planning and dispatch operations to MCP-compatible AI assistants. It works against the live SmartRoutes account associated with the supplied API key and scopes access to that account's depot.

The server supports common depot workflows: finding orders that match filters, inspecting individual orders, checking whether a delivery can fit a time window, reviewing plans and routes, and examining available fleet vehicles and customers. It also includes write operations for creating orders and starting optimisation for a date.

How it works

The hosted endpoint uses Streamable HTTP at https://mcp.smartroutes.io/mcp. Clients send either Authorization: Bearer <api-key> or x-access-key: <api-key>; both headers carry the same SmartRoutes API key. The server also handles legacy SSE clients automatically.

Tools are annotated as read or write operations. list_orders, get_order, check_booking_availability, get_optimisation_status, get_plan, get_route, list_vehicles, get_vehicle, and list_customers are read-only. add_order creates data, while optimise_plan_for_date starts an optimisation job and is additionally marked destructive because auto-dispatch can publish the plan to drivers and notify customers.

For stricter access control, send x-access-scope: read-only. In that mode, the two write tools are removed from the tool list rather than merely hidden from the assistant. Any value other than read-only is rejected.

Setup and configuration

Generate an API key in SmartRoutes under Settings, Integrations, and SmartRoutes Open API. There is no separate MCP credential or refresh-token flow. Treat the key as a secret because it grants access to the account's data.

Configure the endpoint and one authentication header in the MCP client. Claude Desktop, Claude Code, Cursor, and Windsurf examples are provided in the repository, and the same Streamable HTTP endpoint can be used by other compatible clients. Claude Code uses an HTTP MCP entry, Cursor uses Streamable HTTP, and Windsurf uses its serverUrl configuration field.

A local server uses http://localhost:3000/mcp-api, with the port determined by the local application. The production /mcp path is a public alias for the same endpoint.

Tools and capabilities

The smartroutes MCP server provides:

• Order listing with status, customer, order-number, last-updated, and pagination filters.
• Full order lookup and creation of pickup, delivery, or shipment orders.
• Booking checks for an address and requested time window.
• Date-based route optimisation and status polling for the resulting job.
• Plan totals and route summaries, plus per-stop route details.
• Vehicle listings with shifts, capacities, and skills, and full vehicle lookup.
• Customer listing for the depot.

Limitations and notes

The smartroutes MCP server is tied to the SmartRoutes account and depot represented by its API key. The API key is case-sensitive, and Basic and Digest authentication are not supported. Send one accepted authentication header; if both are supplied with different values, the request is rejected.

Read-only annotations depend on the client honouring them, but the x-access-scope: read-only header removes write tools at the server level. Optimisation should be treated carefully because auto-dispatch may publish the plan and contact drivers or customers.