MCP Tools Reference

The MCP server exposes four tools that map one-to-one to the API. Parameter names, value ranges, and business rules match the corresponding endpoints, and tool arguments likewise reject undefined fields (such as taskId instead of task_id).

Tool	Endpoint	Read-only	Uses credits
list_platforms	List platforms	Yes	No
submit_task	Submit a task	No	Successful tasks use credits
get_task	Retrieve a task	Yes	No
list_tasks	List tasks	Yes	No

Each tool returns a block of JSON text (the text in the MCP content), with the same field names as the API.

list_platforms

Lists the available platforms (including any under maintenance), with region, status, both tier prices, and last-24-hour stats.

Parameters: none.

Returns: the same as data.ent from List platforms — platforms and items.

submit_task

Submits a question to a platform and creates a new task. Every call creates a new task that uses credits if it succeeds.

Parameter	Type	Required	Description
platform	string	Yes	Platform ID from list_platforms; skip platforms whose platform_status is maintenance
query	string	Yes	The question, up to 4,096 characters
priority	integer	No	1 = P1 Priority, 2 = P2 Standard (default)
thinking	boolean	No	Whether to request the platform’s thinking mode, default false. Noticeably slower, no extra cost; platforms without a thinking switch run with it off — effective_thinking in the result reports the actual mode. See Thinking mode
country	string	No	Two-letter country code such as US. A dedicated exit for that country isn’t guaranteed
monitor_date	string	No	Business date YYYY-MM-DD (UTC+8), defaults to today. An RFC 3339 timestamp with an offset is converted to its UTC+8 date
wait_seconds	integer	No	0–120, default 0: how long to wait for the task to finish. If it hasn’t finished in time, the current status is returned

Returns: a task summary with the same fields as get_task below. Without wait_seconds, status is usually queued.

get_task

Reads a task’s status and result.

Parameter	Type	Required	Description
task_id	string	Yes	The task ID returned by submit_task or list_tasks
include_raw	boolean	No	When true, also returns the full raw_result (agent steps, media cards, source snippets, and so on). Can be large

Returns: to save model context, a compact task summary by default — no result_json and no full raw_result:

Field	Description
task_id, status, platform, query	Basic task info
monitor_date, priority, country, thinking	Submission parameters; thinking is the requested thinking mode
effective_thinking	Whether thinking was actually on. Present only once there’s a result (success, or a failed platform run), and returned even when false; doesn’t need include_raw
credits	Credits charged or reserved
answer	Answer text (Markdown)
references	Sources; each item has only rank, title, url, domain, and cited
share_link	The platform’s share link
error_code, error_message	Task-level error; error_message is a {"zh","en"} JSON string
created_at, finished_at	Unix seconds
raw_result	Only when include_raw is true; see The Task Object for its structure

Apart from thinking, task_id, status, platform, query, and credits, empty fields are omitted (see the table above for effective_thinking). references[].cited is three-state here too: an absent field means the platform doesn’t make the distinction — don’t treat it as false.

Statuses: queued, dispatching, pending, and running mean the task isn’t finished; a P2 task may go from running back to pending once to retry; succeeded, failed, and canceled are final.

list_tasks

Lists tasks submitted with the API key this connection uses, newest first, without answers. Use it to recover a task_id when a submission result was lost, then call get_task.

Parameter	Type	Description
page	integer	Page number, default 1
page_size	integer	Items per page, default 20, maximum 100
status	string	Only tasks in this status; pending also matches queued and dispatching
platform	string	Only tasks for this platform
keyword	string	Text contained in the query, or an exact task_id
start_time	integer	Lower bound on submission time (Unix seconds, inclusive)
end_time	integer	Upper bound on submission time (Unix seconds, exclusive)

Returns: the same as data.ent from List tasks — total, page, page_size, and items.

Errors

Errors in MCP fall into three groups:

Type	How it shows up	Example
Tool error	A normal tool result with isError: true; the text reads error <code>: <English message> (<Chinese message>)	error 1023: Insufficient credits. Please top up and try again. (点数余额不足，请充值后重试)
Authentication failure	HTTP 401, JSON-RPC error code -32001, with a WWW-Authenticate response header	The key is missing, invalid, disabled, or expired, or was disabled or rolled mid-session
Protocol error	A JSON-RPC error	Unknown tool -32602, unknown method -32601

• Tool error codes are the same as the API’s ret values — see Error Handling. If arguments are wrong, the text reads invalid arguments: …, so the model can fix them and try again.
• When the service is temporarily unavailable, the tool error text is Service unavailable. Please retry later.
• Authentication failures return HTTP 401 rather than a tool error, so your client prompts you to reconfigure the key instead of letting the model retry over and over.

Protocol details

For building your own MCP client or troubleshooting connections:

Item	Details
Endpoint	Accepts POST only; GET (event stream) returns 405
Sessions	Stateless; no Mcp-Session-Id is issued
Responses	Each request gets a single JSON response (Content-Type: application/json); SSE isn’t used
Protocol versions	2025-11-25, 2025-06-18, 2025-03-26, and 2024-11-05. If initialize requests a version outside this list, 2025-11-25 is returned. An unsupported version in the MCP-Protocol-Version header returns HTTP 400
Capabilities	tools only (listChanged: false)
Server info	serverInfo.name is geodata-developer
When the key is checked	On initialize, tools/list, and tools/call
Notifications	Notification messages (no id) return HTTP 202 with no body
Batching	Not supported; the body must be a single JSON-RPC object
Request size	Up to 64 KiB; larger bodies return HTTP 413

JSON-RPC examples

# Initialize
curl -X POST "https://maxaeo.ai/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"}}}'

# Call a tool
curl -X POST "https://maxaeo.ai/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"}}}'

The tools/call response:

{
  "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\":\"chatgpt\",\"query\":\"best mechanical keyboards for programmers\",\"monitor_date\":\"2026-10-26\",\"priority\":2,\"credits\":6,\"answer\":\"For programming, the best mechanical keyboards balance…\",\"references\":[{\"rank\":1,\"title\":\"The Best Mechanical Keyboards for Programmers in 2026\",\"url\":\"https://www.example.com/best-keyboards-for-programmers\",\"domain\":\"www.example.com\"}],\"share_link\":\"https://chatgpt.com/share/…\",\"created_at\":1793018425,\"finished_at\":1793018497}"
      }
    ]
  }
}

Note

The ping method works as a keep-alive check. It doesn’t verify that the key is valid — it only checks the header format. To verify a key, use initialize or tools/list.