MCP 接入

每个能力都以同名 MCP 工具的形式提供，例如 public_holiday、scholarly_search。工具调用和 HTTP 接口走同一条执行路径：相同的参数校验、invocation_id 规则、数据源准入、执行记录、用量和调用日志。

接入信息


地址	`https://services.zgi.im/v1/mcp`
传输	Streamable HTTP，无状态，每个响应都是一个 `application/json` 对象，不使用 SSE 流
鉴权	与 HTTP API 相同：`Authorization: Bearer <服务凭据>`
协议版本	`2026-07-28`（无状态）、`2025-11-25`、`2025-06-18`（握手）

在客户端中配置

claude mcp add --transport http zgi-services https://services.zgi.im/v1/mcp \
  --header "Authorization: Bearer $ZGI_SERVICES_TOKEN"

~/.cursor/mcp.json：

{
  "mcpServers": {
    "zgi-services": {
      "url": "https://services.zgi.im/v1/mcp",
      "headers": { "Authorization": "Bearer zsk_..." }
    }
  }
}

支持远程 MCP（Streamable HTTP）并能设置请求头的客户端都可以接入：

{
  "type": "http",
  "url": "https://services.zgi.im/v1/mcp",
  "headers": { "Authorization": "Bearer zsk_..." }
}

工具

tools/list 只返回你有权限、且至少有一个可用数据源的工具，不分页。
inputSchema 与 HTTP 请求体相同：同样的字段、必填项和字段说明，并且 additionalProperties: false。provider 带有 enum，只列出你可以选择的数据源。
outputSchema 描述成功时的 {execution, result}，与 HTTP 接口 data 中的内容一致。
所有工具都是只读查询：readOnlyHint: true、destructiveHint: false、openWorldHint: true。

调用与错误

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"public_holiday","arguments":{
  "invocation_id":"inv_8842","provider":"holiday-cn","region":"CN",
  "start_date":"2026-10-01","end_date":"2026-10-10"}}}

情况	返回
成功	`isError: false`，`structuredContent` 为 `{execution, result}`，`content[0].text` 是同样内容的 JSON
工具错误（参数校验、数据源失败、重复调用、结果未知等）	`isError: true`，`content[0].text` 是 JSON：`{"error_code", "message", "request_id", "execution"?, "retry_after_seconds"?}`，错误码与 HTTP 接口相同
未知工具，或没有权限的工具	JSON-RPC 错误 `-32602`（两种情况不做区分）

协议细节

2026-07-28（无状态）：每个请求都要带 MCP-Protocol-Version、Mcp-Method，tools/call 还要带 Mcp-Name，并且与请求体中的版本、方法和工具名一致，否则返回 400 和 -32020。未知方法返回 404 和 -32601。支持 server/discover。
2025-11-25、2025-06-18（握手）：通过 initialize 协商版本；请求了不支持的版本时协商为 2025-11-25。
不支持的版本返回 400 和 -32022，data 中列出支持的版本。
不签发 Mcp-Session-Id；批量请求（JSON 数组）返回 -32600；通知（不带 id 的请求）返回 202；GET 和 DELETE 返回 405。

用 curl 调试

curl -sS https://services.zgi.im/v1/mcp \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'