MCP 工具参考

MCP 服务器提供 4 个工具，与开放 API 一一对应。参数名、取值范围和业务规则都与对应接口相同，工具参数同样拒绝未定义的字段（如把 task_id 写成 taskId）。

工具	对应接口	只读	消耗点数
`list_platforms`	查询平台列表	是	否
`submit_task`	提交任务	否	成功的任务扣点数
`get_task`	查询任务	是	否
`list_tasks`	任务列表	是	否

工具的返回内容是一段 JSON 文本（MCP content 中的 text），字段命名与开放 API 相同。

list_platforms

列出已开放的平台（含维护中的平台）及其区域、状态、两档单价和近 24 小时统计。

参数：无。

返回：与查询平台列表的 data.ent 相同，即 platforms 和 items。

submit_task

向一个平台提交问题，创建新任务。每次调用都会创建一个新任务，成功后扣点数。

参数	类型	必填	说明
`platform`	string	是	平台标识，取自 `list_platforms`，跳过 `platform_status` 为 `maintenance` 的平台
`query`	string	是	问题，最长 4096 个字符
`priority`	integer	否	`1` = P1 优先，`2` = P2 标准（默认）
`thinking`	boolean	否	是否请求平台的思考模式，默认 `false`。开启后明显更慢、不加价；没有思考开关的平台按关闭执行，实际模式见返回的 `effective_thinking`。见思考模式
`country`	string	否	两位字母国家代码，如 `US`；不保证该国家有专属出口
`monitor_date`	string	否	业务日期 `YYYY-MM-DD`（北京时间），默认当天；带时区的 RFC 3339 时间会换算为北京时间的日期
`wait_seconds`	integer	否	`0`–`120`，默认 `0`：等待任务结束的秒数，到时间仍未结束则返回当时状态

返回：任务摘要，字段同下方 get_task。不使用 wait_seconds 时，status 通常为 queued。

get_task

读取任务状态与结果。

参数	类型	必填	说明
`task_id`	string	是	`submit_task` 或 `list_tasks` 返回的任务 ID
`include_raw`	boolean	否	为 `true` 时额外返回完整的 `raw_result`（执行过程、多媒体卡片、引用摘要等），内容可能很大

返回：为了节省模型上下文，默认返回精简的任务摘要，不含 result_json 和完整 raw_result：

字段	说明
`task_id`、`status`、`platform`、`query`	任务基本信息
`monitor_date`、`priority`、`country`、`thinking`	提交参数；`thinking` 是请求的思考模式
`effective_thinking`	实际是否开启了思考。拿到结果后（成功，或平台执行失败）才出现，为 `false` 时也会返回；不需要 `include_raw`
`credits`	扣除或预占的点数
`answer`	回答正文（Markdown）
`references`	引用来源，每项只含 `rank`、`title`、`url`、`domain`、`cited`
`share_link`	平台分享链接
`error_code`、`error_message`	任务级错误；`error_message` 是 `{"zh","en"}` JSON 字符串
`created_at`、`finished_at`	Unix 秒
`raw_result`	仅当 `include_raw` 为 `true` 时返回，结构见任务对象

除 thinking、task_id、status、platform、query、credits 外，值为空的字段会被省略（effective_thinking 的规则见上表）。references[].cited 同样是三态：字段不存在表示平台不区分，不能当作 false。

状态说明：queued、dispatching、pending、running 表示未结束；P2 任务可能从 running 回到 pending 再执行一次；succeeded、failed、canceled 为终态。

list_tasks

列出当前连接所用 API Key 提交的任务，按提交时间倒序，不含回答。用于在提交结果丢失时找回 task_id，再调用 get_task。

参数	类型	说明
`page`	integer	页码，默认 `1`
`page_size`	integer	每页条数，默认 `20`，最大 `100`
`status`	string	只看该状态的任务；`pending` 会同时匹配 `queued`、`dispatching`、`pending`
`platform`	string	只看该平台的任务
`keyword`	string	问题包含的文本，或完整的 `task_id`
`start_time`	integer	提交时间下限（Unix 秒，含）
`end_time`	integer	提交时间上限（Unix 秒，不含）

返回：与任务列表的 data.ent 相同：total、page、page_size、items。

错误

MCP 中的错误分三类：

类型	表现	例子
工具错误	正常的工具结果，`isError: true`，文本格式为 `error <错误码>: <英文提示> (<中文提示>)`	`error 1023: Insufficient credits. Please top up and try again. (点数余额不足，请充值后重试)`
鉴权失败	HTTP `401`，JSON-RPC 错误码 `-32001`，响应头带 `WWW-Authenticate`	Key 缺失、无效、已停用、已过期，或使用中途被停用、重置
协议错误	JSON-RPC 错误	未知工具 `-32602`、未知方法 `-32601`

工具错误的错误码与开放 API 的 ret 相同，含义见错误处理。参数写错时文本为 invalid arguments: …，模型可以据此修正参数后重试。
服务暂时不可用时，工具错误文本为 Service unavailable. Please retry later.。
鉴权失败返回 HTTP 401 而不是工具错误，这样客户端会提示你重新配置 Key，而不是让模型反复重试。

协议细节

自行实现 MCP 客户端或排查连接问题时参考：

项目	说明
端点	只接受 `POST`；`GET`（事件流）返回 `405`
会话	无状态，不下发 `Mcp-Session-Id`
响应	每个请求直接返回一个 JSON 响应（`Content-Type: application/json`），不使用 SSE
协议版本	支持 `2025-11-25`、`2025-06-18`、`2025-03-26`、`2024-11-05`；`initialize` 请求的版本不在其中时返回 `2025-11-25`。请求头 `MCP-Protocol-Version` 为不支持的版本时返回 HTTP `400`
能力	只提供 `tools`（`listChanged: false`）
服务器信息	`serverInfo.name` 为 `geodata-developer`
鉴权时机	`initialize`、`tools/list`、`tools/call` 都会校验 Key
通知	通知类消息（没有 `id`）返回 HTTP `202`，无响应体
批量请求	不支持，请求体必须是单个 JSON-RPC 对象
请求体大小	不超过 64 KiB，超出返回 HTTP `413`

JSON-RPC 示例

# 初始化
curl -X POST "https://maxaeo.cn/geoapi/geodata/developer/mcp" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0.0"}}}'

# 调用工具
curl -X POST "https://maxaeo.cn/geoapi/geodata/developer/mcp" \
  -H "Authorization: Bearer $MAXAEO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-06-18" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_task","arguments":{"task_id":"task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23"}}}'

tools/call 的响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"thinking\":false,\"effective_thinking\":false,\"task_id\":\"task_3f6c1d2e-8a4b-4c1f-9e2d-7b5a0c9d1e23\",\"status\":\"succeeded\",\"platform\":\"doubao\",\"query\":\"适合程序员的机械键盘推荐\",\"monitor_date\":\"2026-10-26\",\"priority\":2,\"credits\":3,\"answer\":\"给程序员选机械键盘……\",\"references\":[{\"rank\":1,\"title\":\"2026 年机械键盘选购指南\",\"url\":\"https://www.example.com/keyboard-guide\",\"domain\":\"www.example.com\",\"cited\":true}],\"share_link\":\"https://www.doubao.com/thread/…\",\"created_at\":1793018425,\"finished_at\":1793018497}"
      }
    ]
  }
}