MCP 专栏

MCP 专栏概览

本指南是开发者中心的 Superroute MCP 专栏，涵盖两个服务端、智能体安全模型，以及来自 UserMcpToolCatalog 的实时工具目录。

• User MCP — 供运营/客服智能体管理订单、路线、面单与日报 — https://api.miliexpress.com/mcp
• Developer MCP — 面向集成开发者的指南、Webhook 与打单/建线示例 API — https://api.miliexpress.com/mcp/developer
• 安全：连接级 Bearer、X-MCP-Profile/scopes、高危工具 confirm
• 人工审批队列（propose_write + /mcp-approvals 界面）

什么是 MCP？

模型上下文协议（MCP）是一种开放标准，允许 Claude、Cursor 和 ChatGPT 等 AI 助手与外部工具和服务交互。它使您的 AI 能够在对话中直接执行实际操作，例如追踪包裹。

通过配置 Superroute MCP 服务器，您的 AI 助手无需离开工作流程即可使用物流工具。

两个 MCP 服务

按受众选择正确的服务。不要给无人值守智能体分配带完全权限的 Developer 服务。

快速开始

包裹追踪等公开工具无需认证即可使用。将以下配置添加到您的 MCP 客户端：

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

认证访问

要使用需要用户权限的工具，请在配置中添加您的 API Bearer 令牌：

务必把令牌放在 MCP 连接请求头中，切勿写入工具参数或提示词。

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

如何获取 API 令牌

使用您的凭据调用登录接口：

curl -X POST https://api.miliexpress.com/api/v1/user/login \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "your-password"}'

响应将包含您的访问令牌：

{
  "access_token": "eyJ0eXAiOiJKV1Qi...",
  "token_type": "Bearer",
  "expires_at": "2026-02-20 00:00:00"
}

在 MCP 配置的 Authorization 头中使用 access_token 值。

智能体安全模型

User MCP 面向最小权限智能体。创建 token 时选择 MCP 配置文件（默认运营只读），或通过 header 传递 profile/scopes。

配置文件（X-MCP-Profile）

命名的权限包。无人值守智能体优先 ops-readonly 或 support。

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <ops-readonly-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

可选请求头

高危确认

以下工具在 tools/call 时需要 confirm=true（或使用审批队列）：

• cancel_order
• bulk_create_orders
• reroute_to_address
• build_route
• hold_order
• release_order
• approve_pending_write
• bulk_create_orders_async
• get_shipping_detail
• download_shipping_label
• cancel_shipping_label
• submit_shipping_information
• end_of_day
• uniorder_cancel
• uniorder_purchase_label
• uniorder_create_batch
• uniorder_create_batch_async
• pay_shipping_order
• cancel_shipping_order
• pay_storage_order
• cancel_storage_order
• pay_shipout
• cancel_shipout

人工审批队列

无人值守智能体应提议写操作；由人在应用内或通过 MCP 批准。

1. 智能体：propose_write 或发送 X-MCP-Require-Approval: 1
2. 人：打开 Web 的 MCP 审批，或 list_pending_approvals
3. 人：approve_pending_write（confirm=true）或 reject_pending_write

Web 界面路径（需登录）： /mcp-approvals

Developer MCP 鉴权

优先在连接上使用 Authorization: Bearer。按工具传 api_token 已弃用，将于 2026-12-31 后硬切断。

可用工具

以下工具目前在 MCP 服务器上可用： 93 个来自服务端目录的实时工具

此表在请求时由 UserMcpToolCatalog 生成，与生产环境认证全量 tools/list 保持同步。

客户端配置

选择您的 AI 客户端以获取相应的配置说明：

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-token>",
        "X-MCP-Profile": "ops-readonly"
      }
    }
  }
}

{
  "mcpServers": {
    "mili-express": {
      "type": "url",
      "url": "https://api.miliexpress.com/mcp"
    }
  }
}

{
  "mcpServers": {
    "mili-express": {
      "serverUrl": "https://api.miliexpress.com/mcp"
    }
  }
}

技术细节

• 协议: JSON-RPC 2.0
• 传输方式: HTTP POST (Streamable HTTP)
• 速率限制: 每分钟 60 次请求
• 内容类型: application/json
• 端点: https://api.miliexpress.com/mcp
• 协议版本: 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05
  同一端点同时服务两代协议：以 initialize 握手开始的客户端，以及在每个请求中声明版本的无状态客户端。服务器从不签发会话 ID。
• OAuth 发现: https://api.miliexpress.com/.well-known/oauth-protected-resource
  未认证的请求返回 401，并在 WWW-Authenticate 响应头中给出受保护资源元数据文档的地址。