传输

Documentation Index

Fetch the complete documentation index at: https://mcp.zhcndoc.com/llms.txt

Use this file to discover all available pages before exploring further.

1. stdio，通过标准输入和标准输出进行通信
2. Streamable HTTP

​

stdio

• 服务器从 stdin 读取 JSON-RPC 消息，并向 stdout 写入 JSON-RPC 消息。
• 消息是单独的 JSON-RPC 请求、通知或响应。
• 消息以换行符分隔，且 MUST NOT 包含嵌入的换行符。
• 服务器 MAY 为任何日志目的向 stderr 写入 UTF-8 字符串， 包括信息、调试和错误消息。
• 客户端 MAY 捕获、转发或忽略服务器的 stderr 输出，并且 SHOULD NOT 假定 stderr 输出表示错误条件。
• 服务器 MUST NOT 向其 stdout 写入任何不是有效 MCP 消息的内容。
• 客户端 MUST NOT 向服务器的 stdin 写入任何不是有效 MCP 消息的内容。

​

发送消息

​

接收消息

​

请求元数据

​

取消

​

关闭

1. 关闭子进程（服务器）的输入流。
2. 等待服务器退出。
3. 如果服务器未在合理时间内退出，则使用适合该操作系统的机制强制终止 进程。

​

意外终止

​

向后兼容性

​

Streamable HTTP

​

安全与端点

1. Servers MUST validate the Origin header on all incoming connections to prevent DNS rebinding attacks.
   • If the Origin header is present and invalid, servers MUST respond with HTTP 403 Forbidden. The HTTP response body MAY comprise a JSON-RPC error response that has no id.
2. When running locally, servers SHOULD bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0).
3. Servers SHOULD implement proper authentication for all connections.

​

发送消息

1. 客户端 MUST 使用 HTTP POST 发送 JSON-RPC 消息。
2. 客户端 MUST 在 Accept 头中同时列出 application/json 和 text/event-stream 作为受支持的内容类型。
3. 客户端 MUST 在每个 POST 请求中包含 请求元数据头 。
4. HTTP POST 的正文 MUST 是一个单独的 JSON-RPC request、 notification，或对服务器发起的输入请求的 response（见 接收消息）。
5. 如果正文是 JSON-RPC notification 或对服务器发起的输入请求的 response：
   • 如果服务器接受它，服务器 MUST 返回 HTTP 状态码 202 Accepted，且没有正文。
   • 如果服务器无法接受它，服务器 MUST 返回 HTTP 错误状态码 （例如 400 Bad Request）。HTTP 响应正文 MAY 包含一个没有 id 的 JSON-RPC error response。
6. 如果正文是 JSON-RPC request，服务器 MUST 返回 Content-Type: application/json（单个 JSON 对象）或 Content-Type: text/event-stream（SSE 响应流）之一。 客户端 MUST 同时支持两者。

​

接收消息

• 服务器 MAY 发送 JSON-RPC notifications——例如 notifications/progress 或 notifications/message — 在最终响应之前发送。这些通知 MUST 与 发起该请求的客户端请求相关联。
• 服务器 MUST NOT 在此流上发送独立的 JSON-RPC requests。 服务器到客户端的交互（sampling、elicitation、list-roots）被嵌入为 InputRequiredResult 中的输入请求，遵循 SEP-2322 (MRTR)，而不是作为单独的请求在此或其他任何流上 传递。
• 最终的 JSON-RPC response SHOULD 终止该流。

​

取消

​

请求元数据

​

协议版本头

​

标准请求头

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: DRAFT-2026-v1
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Seattle, WA"
    },
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "DRAFT-2026-v1",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: DRAFT-2026-v1
Mcp-Method: resources/read
Mcp-Name: file:///projects/myapp/config.json

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "resources/read",
  "params": {
    "uri": "file:///projects/myapp/config.json",
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "DRAFT-2026-v1",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

​

来自工具参数的自定义头

Schema 扩展

• MUST NOT 为空
• MUST 仅包含 ASCII 字符（不包括空格和 :）
• 在 inputSchema 中所有 x-mcp-header 值之间 MUST 具有不区分大小写的唯一性
• MUST 仅应用于原始类型参数（number、string、boolean）

{
  "name": "execute_sql",
  "description": "在 Google Cloud Spanner 上执行 SQL",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "执行查询的区域",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "要执行的 SQL 查询"
      }
    },
    "required": ["region", "query"]
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: DRAFT-2026-v1
Mcp-Method: tools/call
Mcp-Name: execute_sql
Mcp-Param-Region: us-west1

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "region": "us-west1",
      "query": "SELECT * FROM users"
    }
  }
}

值编码

• string：按原值使用
• number：转换为十进制字符串表示形式（例如，42、3.14）
• boolean：转换为小写的 "true" 或 "false"

Mcp-Param-{Name}: =?base64?{Base64EncodedValue}?=

客户端行为

1. 从请求正文中提取任何标准头的值（例如， method、params.name、params.uri）。
2. 将 Mcp-Method 头以及（如适用）Mcp-Name 头附加到 请求中。
3. 检查工具的 inputSchema 中标记了 x-mcp-header 的属性，并提取每个参数的值。
4. 按照 值编码 规则对这些值进行编码。
5. 将 Mcp-Param-{Name}: {Value} 头附加到请求中。

自定义头的服务器行为

​

大小写敏感性

​

服务器验证

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"
  }
}

• 缺少必需的标准头（MCP-Protocol-Version、Mcp-Method、 Mcp-Name）。
• 头值与对应的请求正文值不匹配。
• 头值包含无效字符。

​

向后兼容性

• 如果正文包含可识别的现代 JSON-RPC 错误，则表示服务器支持 现代版本的 MCP——应改用宣传的 supported 版本重试 或修正请求，而不是回退。
• 如果正文为空或不是可识别的现代 JSON-RPC 错误，则 回退到 initialize，并在后续请求中继续使用旧版。

• 继续同时托管旧传输的 SSE 和 POST 端点， 以及为 Streamable HTTP 传输定义的新 “MCP endpoint”。
  • 也可以将旧的 POST 端点与新的 MCP endpoint 合并，但这可能会引入不必要的复杂性。

1. 接受来自用户的 MCP 服务器 URL，该 URL 可能指向使用旧传输或新传输的服务器。
2. 尝试向该服务器 URL 发送 POST 请求，并使用如上所定义的 Accept 头：
   • 如果成功，客户端可以假定这是支持 新 Streamable HTTP 传输的服务器。
   • 如果失败并返回 HTTP 状态码 400 Bad Request、404 Not Found 或 405 Method Not Allowed，且响应正文不是 可识别的现代 JSON-RPC 错误（现代服务器会为不支持的版本、未知方法或头验证失败返回此类错误）：
     • 向服务器 URL 发起 GET 请求，期望这会打开 一个 SSE 流，并将 endpoint 事件作为第一个事件返回。
     • 当收到 endpoint 事件时，客户端可以假定这是 运行旧 HTTP+SSE 传输的服务器，并应在后续所有通信中使用该 传输。

​

自定义传输