smartroutes

SmartRoutes MCP 服务

将 SmartRoutes 的路线优化和调度工具提供给 Claude Desktop、Claude Code、Cursor、Windsurf 等 AI 助手使用，也可供任何其他 Model Context Protocol 客户端使用——直接处理实时数据。

概述

MCP 服务将 AI 工具连接到你的 SmartRoutes 实时账户。你可以在聊天中询问 AI 助手哪些订单尚未排期、查看路线计划，或启动优化——所有操作都基于你的真实数据。

它提供与 SmartRoutes REST API 相同的操作，并将其封装为 Agent 可直接调用的简洁工具。所有操作都由你的 API 密钥限定在单个账户内。

可用工具

工具	类型	描述
list_orders	读取	获取站点的订单（可按状态、客户、订单号或最后更新时间筛选；支持分页）
get_order	读取	获取单个订单的完整详情
add_order	写入	创建新订单（取货、配送或货运）
check_booking_availability	读取	检查指定时间段和地址是否可服务
optimise_plan_for_date	写入	为指定日期触发路线优化
get_optimisation_status	读取	轮询优化任务，直到任务完成
get_plan	读取	按计划 ID 获取计划级汇总和路线概览
get_route	读取	获取单条路线中各停靠点的详细信息
list_vehicles	读取	获取车队车辆及其班次、容量和技能
get_vehicle	读取	获取单辆车的完整详情
list_customers	读取	获取站点的客户

每个工具都有注释，以便 AI 客户端区分读取和写入操作。九个读取工具均标记为只读；add_order 和 optimise_plan_for_date 标记为写入操作，而 optimise_plan_for_date 还标记为破坏性操作，因为自动调度会将计划发布给司机并通知客户。会拦截破坏性调用的客户端会在执行前要求你确认。

只读模式

这些注释只是提示，客户端可以选择是否遵循。若要让写入操作完全无法执行，请添加一个标头：

x-access-scope: read-only

此时，服务只会提供九个读取工具。add_order 和 optimise_plan_for_date 会从工具列表中完全移除，无法调用，因此助手不会意外触发这些工具——适合测试期间使用，也适合只需要查询信息的用户。

如需使用完整工具集，请省略此标头。任何其他值都会被拒绝并返回 400，而不会被忽略，因此拼写错误绝不会悄悄恢复写入权限。

{
  "mcpServers": {
    "smartroutes-readonly": {
      "type": "http",
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>",
        "x-access-scope": "read-only"
      }
    }
  }
}

将两个条目并排注册，并按对话选择使用哪个。任何允许设置请求标头的客户端都支持此功能。

设置

1. 获取 API 密钥

MCP 服务使用你现有的 SmartRoutes API 密钥——也就是你当前用于 REST API 的密钥。无需单独的 MCP 凭据、登录流程，也无需刷新或担心过期的令牌。

要生成 API Key，请登录 SmartRoutes 账户，前往 Settings > Integrations > SmartRoutes Open API，然后点击 Generate API Key 按钮。

请将密钥视为机密信息；它可以访问你账户中的数据。

2. 选择发送方式

以下两个请求头均受支持且可以互换——无论使用哪一个，值都是相同的 API 密钥：

请求头	适用场景
Authorization: Bearer <your-api-key>	通用。托管平台如果只提供 Authorization 凭据字段，请使用此项，例如 Mistral Studio 和大多数连接器目录。
x-access-key: <your-api-key>	同样有效，且用法不变。可以自行指定请求头名称时，请使用此项，例如 Claude Code、Claude Desktop、Cursor、Windsurf、VS Code 和你自己的脚本。

请注意以下几点：

• 方案名称不区分大小写——Bearer、bearer 和 BEARER 都有效。密钥本身区分大小写，请准确复制。
• 不支持 Basic 和 Digest。 如果你要配置的工具只提供用户名／密码类型的凭据，请联系我们，不要自行对密钥进行 Base64 编码——这会被拒绝。
• 只发送其中一个。如果同时发送两个且值不同，请求会被拒绝，而不会任选其一，因为猜测可能会让助手连接到错误的账户。两个请求头都发送且值相同则没有问题。

3. 连接你的 AI 工具

每种客户端的即用型配置文件都在 examples/ 中——填入密钥即可使用。

快速开始（Claude Code）

此仓库包含预配置的 .mcp.json。只需替换 <your-api-key>：

{
  "mcpServers": {
    "smartroutes": {
      "type": "http",
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

打开项目时，Claude Code 会自动发现此文件。

Claude Desktop

前往“设置”→“连接器”→“添加自定义连接器”，为 SmartRoutes 添加自定义连接器。

在这里可以添加以下详细信息：

• 名称： SmartRoutes（或你喜欢的名称）
• URL： https://mcp.smartroutes.io/mcp

在同一对话框的“高级设置”／“请求头”中添加身份验证请求头：

• 键： x-access-key
• 值： 你的实际 API 密钥

也可以将以下内容添加到 Claude Desktop 配置文件（claude_desktop_config.json）中：

{
  "mcpServers": {
    "smartroutes": {
      "url": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

Mistral Studio

将 SmartRoutes 注册为连接器：

• URL：https://mcp.smartroutes.io/mcp
• 请求头名称：Authorization
• 请求头值：Bearer <your-api-key>

Mistral 的连接器调试器可在注册前验证服务，并要求凭据使用 Authorization 请求头——这正是上述 Bearer 形式的用途。调试器目前处于公开预览阶段，因此字段标签可能会变动；重要的是 URL 和请求头值。

Cursor

在 Cursor 设置中添加 MCP 服务：

• 名称：smartroutes
• 类型：Streamable HTTP
• URL：https://mcp.smartroutes.io/mcp
• 请求头：x-access-key: <your-api-key>

Windsurf

将以下内容添加到 Windsurf MCP 配置（mcp_config.json）中：

{
  "mcpServers": {
    "smartroutes": {
      "serverUrl": "https://mcp.smartroutes.io/mcp",
      "headers": {
        "x-access-key": "<your-api-key>"
      }
    }
  }
}

任意 MCP 客户端（通用）

此服务使用 Streamable HTTP 传输。两个请求头均可使用：

POST https://mcp.smartroutes.io/mcp
Authorization: Bearer <your-api-key>

POST https://mcp.smartroutes.io/mcp
x-access-key: <your-api-key>

任何支持 Streamable HTTP 的 MCP 客户端都可以连接。旧版 SSE 客户端会自动处理。

4. 本地开发

连接本地运行的服务时，端点为（使用本地应用监听的任意端口）：

http://localhost:3000/mcp-api

请注意，本地路径是 /mcp-api——mcp.smartroutes.io 上较短的 /mcp 是指向同一端点的公共别名。本地环境中两个请求头的用法与生产环境完全相同。

对话示例

连接后，你可以向助手询问：

• “明天有哪些订单还没有安排到路线中？”
• “显示可用车辆及其班次。”
• “周五下午 2–4 点之间，能否安排向 12 Main St 配送？”
• “优化明天所有未完成订单的路线——仅起草，不要派送。”
• “这次优化的状态是什么？”
• “显示 2026-07-01 的计划以及 3 号路线上的停靠点。”
• “为 ACME 在 5 King St 添加一笔 10 kg 的配送。”

API Key 管理

您的 MCP 密钥就是您的 SmartRoutes API 密钥。

操作	说明
使用	使用与 REST API 相同的密钥，通过 Authorization: Bearer 或 x-access-key 发送；密钥限定于一个仓库。
停用	在 SmartRoutes 账户中停用密钥后，MCP 和 REST 访问都会立即被阻止。

故障排除

401 UNAUTHORIZED

服务器未收到可用的密钥。响应正文中的 description 会说明具体情况：

说明	处理方法
No API key provided…	两个请求头都未到达服务器。在托管平台上，请确认请求头确实已保存到连接器，而不只是填写在表单中。
Unsupported Authorization scheme…	您发送了 Basic、Digest 或其他方案。只接受 Bearer。
Authorization header has no credential after the scheme	值为 Bearer，但后面没有内容。
Authorization header must carry exactly one credential	一个请求头值中包含了两个凭据。
Conflicting credentials…	两个请求头都已发送，但值不同。请移除其中一个。
Invalid API Key provided	已收到密钥，但它与任何账户都不匹配。请从 Settings > Integrations 重新复制密钥；通常是因为粘贴的内容被截断。
Attempting to use disabled API key	您的 SmartRoutes 账户中已停用该密钥。请生成一个新密钥。
API Key not authorized for expired trial account	账户的试用期已结束。

每个 401 响应还会包含 WWW-Authenticate: Bearer 响应头。这只是标准方式，用来说明“此处需要 Bearer 令牌”——并不意味着服务器使用 OAuth。 没有登录流程，也没有需要发现的授权服务器，更没有需要获取的 /.well-known/ 元数据。静态 API 密钥就是完整的认证机制。如果您的客户端看到该请求头后尝试启动 OAuth 流程，请将其配置为使用静态请求头凭据。

错误格式

错误使用与 REST API 相同的信封格式，而不是 JSON-RPC 错误对象——身份验证会在到达 JSON-RPC 层之前进行检查：

{
  "name": "UNAUTHORIZED",
  "statusCode": 401,
  "description": "…",
  "details": {}
}

您最可能在对话过程中遇到的异常是速率限制：这类错误会以 MCP 工具结果的形式返回，其中包含 name: "FORBIDDEN" 和 details.retry_after_seconds，因此助手可以稍后重试，而不必断开连接。

安全

• 身份验证：使用您的 API 密钥，通过 Authorization: Bearer <key> 或 x-access-key 请求头发送。系统会拒绝 Basic、Digest 和其他方案。
• 仓库隔离：每个密钥都限定于一个仓库，且所有数据都会按仓库筛选。
• 速率限制：每个工具都有自己的单密钥速率限制（与 REST API 的限制共享）。
• 写入确认：写入工具（add_order、optimise_plan_for_date）会提示助手在运行前进行说明并取得确认，尤其是在自动派发前。
• 共享连接器：注册为工作区或组织可见的连接器会让所有可见用户共用一个 API 密钥，并且我们的审计日志记录的是该密钥，而非具体用户。如需按个人追踪，请将连接器注册为个人连接器。

工作原理

MCP 服务运行的是与 SmartRoutes REST API 相同的引擎——每个工具都会调用相同的底层服务，因此 MCP 和 API 的行为与数据始终一致。传输方式为 Streamable HTTP；身份验证使用您的 API 密钥。

典型的“规划明天的路线”流程：

1. list_orders / list_vehicles — 查看有哪些可用项
2. check_booking_availability — 确认时段（可选）
3. add_order — 输入新工作
4. optimise_plan_for_date — 构建计划（自动派发前请先确认）
5. get_optimisation_status — 轮询，直到任务完成
6. get_plan / get_route — 查看结果