MCP

Every capability is an MCP tool of the same name, such as public_holiday or scholarly_search. A tool call takes the same path as the HTTP endpoint: the same validation, invocation_id rule, provider admission, execution record, usage and call log entry.

Endpoint

URL	https://services.zgi.im/v1/mcp
Transport	Streamable HTTP, stateless; every response is one application/json object, never an SSE stream
Authentication	As for the HTTP API: Authorization: Bearer <service credential>
Protocol versions	2026-07-28 (stateless), 2025-11-25, 2025-06-18 (handshake)

Note

The endpoint serves server-side agents. Requests with an Origin header are refused (403), so browser pages cannot call it.

Client configuration

Claude Code

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

Cursor

~/.cursor/mcp.json:

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

Generic

Any client that supports remote MCP (Streamable HTTP) with custom headers:

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

Tools

• tools/list returns only tools you are scoped for that have at least one available provider; it is not paginated.
• inputSchema is the HTTP request body: the same fields, required list and descriptions, with additionalProperties: false. provider carries an enum of the providers you may select.
• outputSchema describes the success {execution, result}, exactly the HTTP data.
• Every tool is a read-only query: readOnlyHint: true, destructiveHint: false, openWorldHint: true.

Calls and errors

{"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"}}}

Case	Result
Success	isError: false; structuredContent is {execution, result} and content[0].text is the same JSON
Tool error (validation, provider failure, duplicate invocation, unknown outcome, …)	isError: true; content[0].text is JSON {"error_code", "message", "request_id", "execution"?, "retry_after_seconds"?} with the HTTP error codes
Unknown tool, or a tool outside your scopes	JSON-RPC error -32602 (indistinguishable)

Caution

EXECUTION.OUTCOME_UNKNOWN means the provider received the request; agents must not retry automatically. Retrying with the same invocation_id only returns EXECUTION.DUPLICATE_INVOCATION, never a second execution.

Protocol details

• 2026-07-28 (stateless): every request sends MCP-Protocol-Version and Mcp-Method, and tools/call also Mcp-Name, matching the body’s version, method and tool name; otherwise 400 with -32020. Unknown methods return 404 with -32601. server/discover is supported.
• 2025-11-25, 2025-06-18 (handshake): initialize negotiates the version, falling back to 2025-11-25 for an unsupported request.
• An unsupported version returns 400 with -32022, listing the supported versions in data.
• No Mcp-Session-Id is issued; batches (JSON arrays) return -32600; notifications (no id) return 202; GET and DELETE return 405.

Debugging with 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"}'