4Z API

Docs MCP API

Docs MCP API. After a client connects over Streamable HTTP, it can list published catalogs, platforms, tutorials, and operation details. It does not send requests upstream on the client's behalf.

MCP KEY is not checked. When MCP is disabled, the server returns HTTP 403 with body {"error":"MCP is not enabled"}. When it is enabled, the request is allowed.

Endpoint

Environment Method Path
Production POST https://efwef.xyz/api/docs/mcp

Content-Type: application/json. The request body is limited to 1 MiB. The same client IP is limited to 60 requests per minute. Above that limit the server returns HTTP 429 with body {"error":"too many requests"}.

GET returns HTTP 405 with body {"error":"MCP endpoint accepts POST only"}. This service does not use SSE.

Client configuration

Do not put an MCP KEY in the configuration:

{
  "mcpServers": {
    "docs-mcp": {
      "url": "https://efwef.xyz/api/docs/mcp"
    }
  }
}

Protocol

One stateless JSON-RPC 2.0 message. Server name: docs-mcp.

Handshake:

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}

On success the response is HTTP 200 and result.serverInfo.name is docs-mcp. If the client omits protocolVersion, the server falls back to 2025-06-18. If the client sends one, the server echoes it.

method Description
initialize Handshake. Returns capabilities and instructions
notifications/initialized, initialized Notification. When there is no id, HTTP 202 with an empty body
ping result is an empty object
tools/list Returns the five tools below
tools/call params.name plus params.arguments

An unknown method that includes an id returns HTTP 200 with error.code -32601. If jsonrpc is not 2.0, error.code is -32600.

Tool output is in result.content[0].text: a JSON string, or a one-line error message. Business errors (not found, bad arguments) still return HTTP 200, with result.isError set to true. On success, isError is omitted.

Tools

The locale argument accepts only zh-CN (the default) and en-US. Any other value is treated as zh-CN. For list tools, limit defaults to 20 and the maximum is 50. An offset below 0 is treated as 0.

docs_list_catalog

Catalog nodes.

Arguments: locale, limit, offset. All optional.

items[] fields: id, parentId, type, title, slug, sortOrder, published. Also total, count, offset, has_more.

docs_list_platforms

Published API platforms.

Arguments: locale, limit, offset.

items[] fields: platform, title, isDetailed, yamlBytes. Also total, count, offset, has_more.

docs_get_tutorial

Fetch one published tutorial by slug.

Arguments: slug (required), locale.

Success fields: title, slug, markdown, truncated, publishedAt. A body longer than 20 KiB is truncated and truncated is true.

Drafts, tutorials unreachable from the catalog, or tutorials not visible on the current Host return isError=true and text containing tutorial not found.

docs_list_operations

HTTP operations under one published platform.

Arguments: platform (required, for example v1), locale, limit, offset.

Success fields: platform, title, and items[] with id, method, path, summary, tag, deprecated. Also total, count, offset, has_more. id is the opId for the next call.

If the platform is not published, isError=true and the text contains platform not found.

docs_get_operation

Parameters, request body, responses, and examples for one published operation. The operation is not executed.

Arguments: platform and opId (both required), locale.

The success body is an OperationView. Main fields: id, method, path, summary, description, deprecated, tag, servers, baseUrl, parameters, requestBody, responses.

If the operation is not found, isError=true and the text contains operation not found.

Call order

  1. docs_list_platforms or docs_list_catalog
  2. docs_list_operations, passing platform
  3. docs_get_operation, passing platform and the id from the previous step
  4. For a tutorial, call docs_get_tutorial with the catalog slug

Do not invent a path or operationId that did not appear in a list.