Connect SmartRoutes to AI assistants like Claude, Cursor and Mistral with the SmartRoutes MCP Server.
AI assistants are quickly becoming part of how teams get work done. With the SmartRoutes MCP Server, you can bring your route planning and dispatch data straight into those conversations.
Ask your AI assistant which orders are still unscheduled, review a route plan, or kick off an optimization, all in chat and against your live SmartRoutes data.
This guide covers what the MCP server is, what it can do, and a high-level view of how to get set up.
What is the SmartRoutes MCP Server?
MCP stands for Model Context Protocol, an open standard that lets AI assistants connect to outside tools and data. Think of it as a universal plug that lets an AI agent talk to the software you already use.
The SmartRoutes MCP Server connects an AI tool to your SmartRoutes account. It exposes the same operations as the SmartRoutes Open API, shaped as simple tools an AI agent can call directly. That means no custom code and no copying data between windows.
It works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code, Mistral Studio, and any other MCP client that supports Streamable HTTP.
What can you do with it?
Once connected, your AI assistant can look up orders, vehicles and customers, check whether a delivery slot can be served, add new orders, and trigger route optimization for a given day.
Available tools:
| Tool | Type | What it does |
|---|---|---|
list_orders | Read | Lists orders for your depot, filtered by status, customer, order number, or last-updated time. |
get_order | Read | Returns full detail for a single order. |
add_order | Write | Creates a new pickup, delivery, or shipment order. |
check_booking_availability | Read | Checks whether a time window and address can be served. |
optimise_plan_for_date | Write | Triggers route optimization for a date. |
get_optimisation_status | Read | Checks on an optimization job until it finishes. |
get_plan | Read | Returns plan-level totals and a route summary. |
get_route | Read | Returns per-stop detail for a single route. |
list_vehicles | Read | Lists fleet vehicles with shifts, capacities, and skills. |
get_vehicle | Read | Returns full detail for a single vehicle. |
list_customers | Read | Lists customers for your depot. |
Example questions you can ask:
- "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 and 4pm on Friday?"
- "Optimize tomorrow's routes for all open orders, but don't dispatch yet."
- "Show me the plan for July 1st and the stops on route 3."
- "Add a 10 kg delivery for ACME at 5 King St."
How it works, using a typical "plan tomorrow's routes" request:
- The assistant checks which orders and vehicles are available.
- If needed, it confirms a delivery slot can be served and adds any new orders.
- It triggers route optimization for tomorrow, confirming with you first.
- Once optimization finishes, it reads back the plan and route details for you to review.
Because the MCP server runs on the same engine as the SmartRoutes Open API, the results always match what you see in SmartRoutes.
Staying in control
Giving an AI assistant access to your live data is a big step, so the MCP server is built with a few safeguards.
- Write confirmation: Only two tools can change data: add_order and optimise_plan_for_date. Both tell the assistant to explain what it's about to do and confirm with you first. Optimization is flagged as destructive, because auto-dispatch publishes routes to drivers and notifies customers.
- Read-only mode: Add the header x-access-scope: read-only to your connection and the write tools disappear entirely. This is useful while you're testing, or for team members who only need to look things up.
- Depot isolation: Every API key is scoped to a single depot, so the assistant only ever sees that depot's data.
- Rate limiting: Each tool has its own rate limit, shared with the Open API's limits.
It's worth setting up both a read-only and a full-access connection side by side, then choosing the right one for each conversation.
How to get set up
Setup takes a few minutes. The MCP server uses your existing SmartRoutes API key, so there's no separate login, sign-in flow or token to refresh.
Step 1: Generate your API key
- Go to Settings > Integrations.
- Select SmartRoutes Open API.
- Click Generate API Key.
If you already use the Open API, you can use the same key. Treat it as a secret, since it grants access to your account's data.
Step 2: Connect your AI tool
In your AI tool, add a new MCP server or connector with these details:
- URL: https://mcp.smartroutes.io/mcp
- Header: x-access-key: YOUR_API_KEY
Some hosted platforms, like Mistral Studio, only offer an Authorization field. In that case, use Authorization: Bearer YOUR_API_KEY instead.
Using Claude Desktop as an example:
- Go to Settings > Connectors > Add custom connector.
- Enter a Name (for example, SmartRoutes) and the URL above.
- Under Advanced settings, add a request header with the key x-access-key and your API key as the value.
- Save, and start asking questions about your SmartRoutes data.
Ready-to-copy config files for Claude Code, Claude Desktop, Cursor, Windsurf and VS Code are available on our GitHub page.
A few things to note
- Send only one of the two headers. If both are sent with different values, the request is rejected.
- Only Bearer authentication is supported. Basic and Digest credentials will be rejected.
- Disabling your API key in SmartRoutes immediately blocks both MCP and Open API access.
Learn more
This guide covers the basics. For full setup instructions for every supported client, read-only configuration examples, and troubleshooting tips, visit the SmartRoutes MCP Server on GitHub.
Related Guides
- Integrations & API: How does it work?
- How to Add Stops in SmartRoutes
- How to Integrate with Shopify
- How to Integrate with WooCommerce
Didn’t answer your question?
You can see our other guides here or contact support at support@smartroutes.io.
Please provide us with some additional feedback
Thanks for your feedback. It is greatly appreciated