Deep Dive into MCP Streamable HTTP Message Formats

MCP supports three communication modes: stdio (using stdin/stdout for local tool integration), SSE (Server‑Sent Events for real‑time updates, limited by connection count), and the newer Streamable HTTP protocol introduced on 2025‑03‑26 to replace the traditional HTTP + SSE combination.

Streamable HTTP consolidates the endpoint and provides dynamic streaming, addressing long‑connection resource consumption and disconnection recovery while retaining real‑time push capabilities. The protocol is currently used in production and is divided into four stages: initialization , runtime , update , and closure . Each stage consists of several JSON‑RPC messages.

1. Initialization stage

Client sends a POST /mcp request with method":"initialize" to negotiate protocol version and capabilities. Example request:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": "65e340ea-0",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {"roots": {"listChanged": true}},
    "clientInfo": {"name": "Java SDK MCP Client", "version": "1.0.0"}
  }
}

The server replies with HTTP 200 and a JSON payload containing the agreed protocol version, capabilities, and server information.

{
  "jsonrpc": "2.0",
  "id": "65e340ea-0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "logging": {},
      "prompts": {"listChanged": true},
      "resources": {"subscribe": true, "listChanged": true},
      "tools": {"listChanged": true}
    },
    "serverInfo": {"name": "示例MCP服务器", "version": "1.0.0"}
  }
}

After initialization, the client sends a notifications/initialized message to confirm the connection, receiving an empty HTTP 202 response.

{"jsonrpc":"2.0","method":"notifications/initialized"}

The server also supports an SSE‑based initialization request ( GET /mcp) which is shown for completeness.

2. Runtime stage

During runtime the client can request tool lists, prompt lists, and resource lists, then invoke tools or read resources.

Tool list : POST /mcp with method":"tools/list". The server returns an array of tool descriptors, e.g., a weather‑lookup function with its JSON schema.

Prompt list : POST /mcp with method":"prompts/list". The response contains prompt objects, each with name, description, and argument definitions.

Resource list : POST /mcp with method":"resources/list". The response enumerates available resources (URI, name, description, mimeType).

Example tool‑call request:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": "65e340ea-2",
  "params": {"name": "getWeather", "arguments": {"arg0": "北京"}}
}

The server replies with the weather result wrapped in a content array.

{
  "jsonrpc": "2.0",
  "id": "65e340ea-2",
  "result": {
    "content": [{"type": "text", "text": "北京: 晴天，温度25℃"}],
    "isError": false
  }
}

Resource reading uses method":"resources/read" with a uri parameter, returning the resource contents.

{
  "jsonrpc": "2.0",
  "method": "resources/read",
  "id": "65e340ea-4",
  "params": {"uri": "test://resource"}
}

Prompt retrieval uses method":"prompts/get" with the prompt name, and the server returns the prompt messages, including embedded resources.

{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "id": "65e340ea-6",
  "params": {"name": "test-prompt-embeddedResource", "arguments": {}}
}

Response includes a message with a resource object (URI, mimeType, text).

3. Update stage

The server can push a notifications/tools/list_changed SSE message when the tool list changes. The client receives the notification and issues a fresh tools/list request to refresh its local cache.

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed",
  "params": {}
}

4. Closure stage

The article mentions a closing phase but does not provide concrete messages; it is left as a placeholder for future implementation.