MCP 接入 (AI 客户端)

把 CZL Express 的查价、轨迹、偏远查询等能力接进 CZL Agent、Claude、Cursor 等支持 MCP (Model Context Protocol) 的 AI 客户端，直接用自然语言提问，例如“5kg 40×30×30 的箱子寄美国 10001 哪个渠道最便宜”。

接入地址

端点	鉴权	可用工具	额度
`https://tms-go.czl.net/api/mcp/public`	无需鉴权	公开工具	每个 IP 每 5 分钟 30 次、每天 300 次
`https://tms-go.czl.net/api/mcp`	`Authorization: Bearer <API_KEY>` 或 `X-API-Key: <API_KEY>`	公开工具 + 账号工具；管理员账号另有录单工具	按接口平台为 `/api/mcp` 配置的每日限额，管理员不限

传输方式: Streamable HTTP (无状态)
额度按工具调用次数计算，连接握手和获取工具列表不计数
API Key 与接口平台通用，在控制台「API密钥」页创建；非管理员账号使用 /api/mcp 需要管理员在接口平台为其开通 MCP 接入 权限，未开通返回 403

客户端配置

CZL Agent (ai.czl.net)

我司自有 Agent，MCP 能力在 CZL AI 桌面端里提供 (网页版不能接本机 MCP)。两种方式任选：

直接在对话里让 CZL Agent 接入本 MCP 并把这份文档发给它，它会自行安装 (写入桌面端的 config/mcp.json，安装前弹窗确认)，装好后自动加入「始终启用」
手动在「设置 → 桌面端」的 MCP 配置里添加 (格式同 Claude Code 的 mcpServers)：

json

{
  "mcpServers": {
    "czl": {
      "type": "http",
      "url": "https://tms-go.czl.net/api/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

没有 API Key 时把 url 换成公开端点 https://tms-go.czl.net/api/mcp/public 并去掉 headers。已在 Claude Code / Codex 里配置过本 MCP 的，桌面端会自动读取，无需重复添加。

Claude Code

bash

# 公开端点
claude mcp add --transport http czl https://tms-go.czl.net/api/mcp/public

# API Key 端点
claude mcp add --transport http czl https://tms-go.czl.net/api/mcp --header "Authorization: Bearer your_api_key"

Cursor / Windsurf / Cline 等 (mcp.json)

json

{
  "mcpServers": {
    "czl": {
      "url": "https://tms-go.czl.net/api/mcp",
      "headers": {
        "Authorization": "Bearer your_api_key"
      }
    }
  }
}

Claude 网页版 / 桌面版 (自定义连接器)

在「设置 → 连接器 → 添加自定义连接器」中填入公开端点 https://tms-go.czl.net/api/mcp/public。自定义连接器只支持 OAuth 鉴权，不能携带 API Key，因此只能使用公开工具。

公开工具

工具	说明
`query_price`	按目的国、邮编、包装类型 (`P` 包裹 / `D` 文件 / `B` 袋子) 与包裹尺寸重量查询各渠道报价 (人民币)，按总价从低到高返回最便宜的 30 个渠道。结果不含偏远附加费。渠道说明 (禁运、理赔、退件规则) 默认不返回，用 `product_keyword` 筛到 5 个以内渠道并设 `include_notes: true` 时返回
`track_shipment`	查询运单轨迹，合并我司系统与 DHL / FedEx / UPS 等承运商官方轨迹，附可发给客户的轨迹页链接。匿名每次 1 个单号，API Key 每次最多 5 个
`query_remote`	查询收件地对 DHL / FedEx / UPS / TNT 及自定义渠道是否偏远。结果含 `query_cities` 时表示该邮编对应多个城市，需带 `selected_city` 再查一次
`calc_chargeable_weight`	按尺寸与实重计算体积重和计费重，默认除数 5000，可传 `divisor` (如 6000)
`get_fuel_surcharge`	查询 DHL / FedEx / UPS 当前及近期燃油附加费率

国家一律使用 ISO 3166-1 二字码 (US、GB、DE)，重量单位 kg，尺寸单位 cm。

账号工具 (需 API Key)

工具	说明
`get_my_usage`	当前 API Key 所属账号的调用量、近 7 天趋势、各接口权限、每日限额与今日已用次数

管理员工具 (需管理员账号的 API Key)

管理员账号的 API Key 连接 /api/mcp 时额外提供录单工具：把客户发来的文字、图片、表格交给 AI 客户端，由它整理成结构化订单后直接录入。

工具	说明
`create_order`	建一张本地录单，返回本地订单 ID 与订单号。只写本系统，不上传物流通、不发新订单通知，可在后台订单详情页人工核对修改
`list_orders`	分页查看录单 (按创建时间倒序)，支持按客户代码 / 订单 ID / 收件人 / 电话搜索，含上传状态、处理状态、物流单号与收发货时间
`get_order`	按订单 ID 查看收件人、申报物品、箱体尺寸重量、关税与报关方式
`upload_order_to_tms`	上传订单到物流通建单。不可撤销，客户端会在调用前请求确认；已上传过的订单再次上传必须带重传后缀 `order_code_suffix` (如 `-1`)

错误码

工具执行失败时返回 isError: true，文本为“数字码 + 英文说明”：

错误码	含义
`40001`	参数错误，按说明修正后重试 (不计入匿名额度)
`40301`	账号未开通 MCP 权限
`42901`	账号今日调用已达每日限额
`42902`	匿名 IP 额度已用完，可改用 API Key 端点
`50201`	上游查询失败，可稍后重试
`50202`	物流通拒绝建单，文本附带拒单原因 (仅管理员工具)
`50001`	服务内部错误

HTTP 层面：API Key 端点缺少或携带无效 Key 返回 401，Key 有效但未开通权限返回 403。

调用示例 (JSON-RPC)

bash

curl --request POST \
  --url https://tms-go.czl.net/api/mcp/public \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "calc_chargeable_weight",
      "arguments": {
        "packages": [{ "weight_kg": 3.2, "length_cm": 40, "width_cm": 30, "height_cm": 30, "count": 2 }]
      }
    }
  }'