[{"_1":2,"_3":-5,"_4":-5},"loaderData",{"_5":6,"_7":8,"_9":10},"actionData","errors","root",{"_111":112},"routes/modules.$creator.$moduleId",{"_14":15,"_16":17,"_18":19,"_20":21},"routes/modules.$creator.$moduleId.endpoints",{"_11":12,"_13":-5},"error","Module not found","tools","module",{"_20":22,"_23":24,"_25":26,"_27":28,"_29":30,"_31":32,"_33":34,"_35":26,"_36":37,"_38":-5,"_39":-5,"_40":41,"_42":43,"_44":45,"_46":47,"_48":49,"_50":51,"_52":53,"_54":55,"_56":-5,"_57":49,"_58":59,"_60":61,"_62":63,"_64":65,"_66":67,"_68":69,"_70":71,"_72":73,"_74":75,"_76":77,"_78":79,"_80":-5,"_81":-5,"_82":-5,"_83":49,"_84":-5,"_85":59,"_86":87,"_88":89,"_90":91,"_92":93,"_94":95,"_96":97},"apiUrl","https://odel.app/api","creator","smartroutes-io","moduleId","smartroutes-mcp","@smartroutes-io/smartroutes-mcp","displayName","smartroutes mcp","tagline","Route optimisation, orders, booking and fleet management for a SmartRoutes depot.","iconKey","https://avatars.githubusercontent.com/u/298237026?v=4","category","remote","status","published","visibility","public","metaDescription","deploymentType","external","workerName","bindingName","mcpConfig","{\"url\":\"https://mcp.smartroutes.io/mcp\",\"transport\":\"streamable-http\",\"authType\":\"none\"}","pricingModel","free","creatorUserId","system:external-import","createdAt",1783744351000,"updatedAt",1788333455000,"sourceRegistry","official-mcp-registry","sourceUrl","https://registry.modelcontextprotocol.io/v0/servers?search=io.smartroutes%2Fsmartroutes","sourceVerified",false,"sourceMissingSince","importedAt","upstreamStars",0,"upstreamUpdatedAt",1787742033000,"detectedTransport","streamable-http","detectedAuthType","bearer","probeStatus","ok","lastProbedAt",1787636583000,"githubRepoUrl","https://github.com/SmartRoutes-io/smartroutes-mcp","githubRepoFullName","SmartRoutes-io/smartroutes-mcp","releaseId","ext-smartroutes-io-smartroutes-mcp","version","1.0.0","descriptionMarkdown","# SmartRoutes MCP Server\n\nExpose your SmartRoutes route-optimisation and dispatch tools to AI assistants like Claude Desktop, Claude Code, Cursor, Windsurf, and any other [Model Context Protocol](https://modelcontextprotocol.io) client — working against your live data.\n\n## Overview\n\nThe 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.\n\nIt 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.\n\n## Available Tools\n\n| Tool | Type | Description |\n| ----------------------------- | ----- | ----------------------------------------------------------------- |\n| `list_orders` | Read | Orders for the depot (filter by status, customer, order number, or last-updated time; paginated) |\n| `get_order` | Read | Full detail for a single order |\n| `add_order` | Write | Create a new order (pickup, delivery, or shipment) |\n| `check_booking_availability` | Read | Whether a time window + address can be served |\n| `optimise_plan_for_date` | Write | Trigger route optimisation for a date |\n| `get_optimisation_status` | Read | Poll an optimisation job until it finishes |\n| `get_plan` | Read | Plan-level totals and route summary, by plan id |\n| `get_route` | Read | Per-stop detail for a single route |\n| `list_vehicles` | Read | Fleet vehicles with shifts, capacities, and skills |\n| `get_vehicle` | Read | Full detail for a single vehicle |\n| `list_customers` | Read | Customers for the depot |\n\nEvery tool is annotated so your AI client can tell reads from writes. The nine read tools are marked read-only; `add_order` and `optimise_plan_for_date` are marked as writes, and `optimise_plan_for_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.\n\n### Read-only mode\n\nThose annotations are hints your client chooses to honour. To make writes **impossible**, add one header:\n\n```\nx-access-scope: read-only\n```\n\nThe server then exposes only the nine read tools. `add_order` and `optimise_plan_for_date` 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.\n\nOmit 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.\n\n```json\n{\n \"mcpServers\": {\n \"smartroutes-readonly\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.smartroutes.io/mcp\",\n \"headers\": {\n \"x-access-key\": \"\",\n \"x-access-scope\": \"read-only\"\n }\n }\n }\n}\n```\n\nRegister both entries side by side and pick per conversation. Any client that lets you set request headers supports this.\n\n## Setup\n\n### 1. Get your API key\n\nThe 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.\n\nTo 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.\n\nTreat the key as a secret; it grants access to your account's data.\n\n### 2. Choose how to send it\n\nTwo headers are accepted and they are interchangeable — the value is the same API key either way:\n\n| Header | When to use it |\n| ------ | -------------- |\n| `Authorization: Bearer ` | Works everywhere. Use this on hosted platforms whose only credential field is `Authorization` — Mistral Studio and most connector directories. |\n| `x-access-key: ` | Equally valid and unchanged. Use it wherever you can name the header yourself: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, your own scripts. |\n\nA few things worth knowing:\n\n- The scheme word is case-insensitive — `Bearer`, `bearer` and `BEARER` all work. The key itself is case-sensitive, so copy it exactly.\n- **`Basic` and `Digest` are not supported.** If the tool you're configuring only offers a username/password style credential, get in touch rather than base64-encoding the key yourself — it will be rejected.\n- Send **one** of the two. If both are present with different values the request is rejected rather than one being picked, because guessing could point the assistant at the wrong account. Sending both with the *same* value is fine.\n\n### 3. Connect your AI tool\n\n> Ready-to-copy config files for every client live in [`examples/`](https://github.com/SmartRoutes-io/smartroutes-mcp/blob/main/examples/) — drop in your key and go.\n\n#### Quick start (Claude Code)\n\nThis repo includes a pre-configured [`.mcp.json`](https://github.com/SmartRoutes-io/smartroutes-mcp/blob/main/.mcp.json). Just replace ``:\n\n```json\n{\n \"mcpServers\": {\n \"smartroutes\": {\n \"type\": \"http\",\n \"url\": \"https://mcp.smartroutes.io/mcp\",\n \"headers\": {\n \"x-access-key\": \"\"\n }\n }\n }\n}\n```\n\nClaude Code auto-discovers this file when you open the project.\n\n#### Claude Desktop\n\nAdd a Custom Connector for SmartRoutes by going to: Settings → Connectors → Add custom connector\n\nHere you can add the following details:\n- **Name:** SmartRoutes (or whatever you like)\n- **URL:** https://mcp.smartroutes.io/mcp\n\nAdd your authentication header under Advanced settings / Request headers in that same dialog:\n- **Key:** x-access-key\n- **Value:** your actual API key\n\nAlternatively, you can add the following to your Claude Desktop config (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"smartroutes\": {\n \"url\": \"https://mcp.smartroutes.io/mcp\",\n \"headers\": {\n \"x-access-key\": \"\"\n }\n }\n }\n}\n```\n\n#### Mistral Studio\n\nRegister SmartRoutes as a **Connector**:\n\n- **URL**: `https://mcp.smartroutes.io/mcp`\n- **Header name**: `Authorization`\n- **Header value**: `Bearer `\n\nMistral's Connectors Debugger lets you validate a server before registering it, and it asks for the credential as an `Authorization` header — which is exactly what the Bearer form above is for. The Debugger is in public preview, so field labels may move; the URL and the header value are what matter.\n\n#### Cursor\n\nIn Cursor settings, add an MCP server:\n\n- **Name**: smartroutes\n- **Type**: Streamable HTTP\n- **URL**: `https://mcp.smartroutes.io/mcp`\n- **Headers**: `x-access-key: `\n\n#### Windsurf\n\nAdd to your Windsurf MCP config (`mcp_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"smartroutes\": {\n \"serverUrl\": \"https://mcp.smartroutes.io/mcp\",\n \"headers\": {\n \"x-access-key\": \"\"\n }\n }\n }\n}\n```\n\n#### Any MCP Client (generic)\n\nThe server uses **Streamable HTTP** transport. Either header works:\n\n```text\nPOST https://mcp.smartroutes.io/mcp\nAuthorization: Bearer \n```\n\n```text\nPOST https://mcp.smartroutes.io/mcp\nx-access-key: \n```\n\nAny MCP client that speaks Streamable HTTP can connect. Legacy SSE clients are handled automatically.\n\n### 4. Local development\n\nAgainst a locally-running server the endpoint is (use whatever port your local app listens on):\n\n```text\nhttp://localhost:3000/mcp-api\n```\n\nNote the path is `/mcp-api` locally — the shorter `/mcp` on `mcp.smartroutes.io` is a public alias for the same endpoint. Both headers work locally exactly as they do in production.\n\n## Example Conversations\n\nOnce connected, you can ask your assistant things like:\n\n- \"What orders for tomorrow aren't on a route yet?\"\n- \"Show me available vehicles and their shifts.\"\n- \"Can we fit a delivery to 12 Main St between 2–4pm on Friday?\"\n- \"Optimise tomorrow's routes for all open orders — draft only, don't dispatch yet.\"\n- \"What's the status of that optimisation?\"\n- \"Show me the plan for 2026-07-01 and the stops on route 3.\"\n- \"Add a 10 kg delivery for ACME at 5 King St.\"\n\n## API Key Management\n\nYour MCP key **is** your SmartRoutes API key.\n\n| Action | Description |\n| ----------- | -------------------------------------------------------------------------------------- |\n| **Use** | The same key as the REST API, sent as either `Authorization: Bearer` or `x-access-key`; scoped to one depot. |\n| **Disable** | Disabling a key in your SmartRoutes account immediately blocks both MCP and REST access. |\n\n## Troubleshooting\n\n### `401 UNAUTHORIZED`\n\nThe server didn't get a usable key. The `description` in the response body tells you which case you hit:\n\n| Description | What to do |\n| ----------- | ---------- |\n| `No API key provided…` | Neither header reached the server. On hosted platforms, check the header was actually saved onto the connector rather than just typed into the form. |\n| `Unsupported Authorization scheme…` | You sent `Basic`, `Digest` or something else. Only `Bearer` is accepted. |\n| `Authorization header has no credential after the scheme` | The value is `Bearer` with nothing after it. |\n| `Authorization header must carry exactly one credential` | Two credentials ended up in one header value. |\n| `Conflicting credentials…` | Both headers were sent with different values. Remove one. |\n| `Invalid API Key provided` | The key arrived but doesn't match an account. Re-copy it from Settings > Integrations — a truncated paste is the usual cause. |\n| `Attempting to use disabled API key` | The key was disabled in your SmartRoutes account. Generate a new one. |\n| `API Key not authorized for expired trial account` | The account's trial has ended. |\n\nEvery 401 also carries a `WWW-Authenticate: Bearer` response header. That is just the standard way of saying \"a Bearer token is expected here\" — **it does not mean the server uses OAuth.** There is no sign-in flow, no authorisation server to discover, and no `/.well-known/` metadata to fetch. The static API key is the whole mechanism. If your client tries to start an OAuth flow after seeing that header, configure it with a static header credential instead.\n\n### Error shape\n\nErrors use the same envelope as the REST API, not a JSON-RPC error object — authentication is checked before the JSON-RPC layer is reached:\n\n```json\n{\n \"name\": \"UNAUTHORIZED\",\n \"statusCode\": 401,\n \"description\": \"…\",\n \"details\": {}\n}\n```\n\nRate limits are the exception you're most likely to see mid-conversation: those come back as an MCP tool result with `name: \"FORBIDDEN\"` and `details.retry_after_seconds`, so the assistant can back off and retry rather than dropping the connection.\n\n## Security\n\n- **Authentication**: your API key, sent as either `Authorization: Bearer ` or the `x-access-key` header. `Basic`, `Digest` and other schemes are rejected.\n- **Depot isolation**: every key is scoped to a single depot, and all data is filtered by depot.\n- **Rate limiting**: each tool has its own per-key rate limit (shared with the REST API's limits).\n- **Write confirmation**: write tools (`add_order`, `optimise_plan_for_date`) instruct the assistant to explain and confirm before running — especially auto-dispatch.\n- **Shared connectors**: a connector registered at workspace or organisation visibility shares one API key across everyone who can see it, and our audit log records the key rather than the individual user. Register it personally if you need per-person attribution.\n\n## How it works\n\nThe 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.\n\nA typical \"plan tomorrow's routes\" flow:\n\n1. `list_orders` / `list_vehicles` — see what's available\n2. `check_booking_availability` — confirm a slot (optional)\n3. `add_order` — enter new work\n4. `optimise_plan_for_date` — build the plan (confirm before auto-dispatch)\n5. `get_optimisation_status` — poll until it finishes\n6. `get_plan` / `get_route` — read the result\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays","iconType","image","upstream",{"_100":101,"_102":103,"_104":-5,"_105":106,"_107":108,"_109":110},"requiredSecrets",[],"tags",[],"assets",[],"stats",{"_98":59,"_99":59},"ratingAvg","reviewCount","topics",[],"license","MIT","language","registryName","io.smartroutes/smartroutes","homepage","https://smartroutes.io/api","packages",[],"ENV",{"_113":114,"_115":116,"_117":118},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]