Streamable HTTP

• The server exposes a single HTTP endpoint (the MCP endpoint) that accepts POST.
• The client sends every JSON-RPC request or notification as its own HTTP POST.
• The server answers each request with either a single JSON object or a Server-Sent Events (SSE) stream scoped to that request, carrying request-related notifications followed by the final response.
• Server-to-client interactions (sampling, elicitation, roots) are embedded in results as input requests per Multi Round-Trip Requests (MRTR) (SEP-2322).
• Long-lived change notifications (such as list changes and resource updates) are delivered on the response stream of a subscriptions/listen request.

​

Security & Endpoint

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.

​

Sending Messages

1. The client MUST use HTTP POST to send JSON-RPC messages.
2. The client MUST include an Accept header listing both application/json and text/event-stream as supported content types.
3. The client MUST include the request metadata headers on each POST request.
4. The body of the HTTP POST MUST be a single JSON-RPC request or notification. The client MUST NOT send JSON-RPC responses.
5. If the body is a JSON-RPC notification:
   • If the server accepts it, the server MUST return HTTP status code 202 Accepted with no body.
   • If the server cannot accept it, it MUST return an HTTP error status code (e.g., 400 Bad Request). The HTTP response body MAY comprise a JSON-RPC error response that has no id.
6. If the body is a JSON-RPC request, the server MUST return either Content-Type: application/json (a single JSON object) or Content-Type: text/event-stream (an SSE response stream). The client MUST support both.

​

Receiving Messages

• The server MAY send JSON-RPC notifications — for example, notifications/progress or notifications/message — before the final response. These notifications MUST relate to the originating client request.
• The server MUST NOT send independent JSON-RPC requests on this stream. Server-to-client interactions (sampling, elicitation, list-roots) are embedded as input requests inside an InputRequiredResult per MRTR (SEP-2322), not delivered as separate requests on this or any other stream. This is a change from Streamable HTTP in protocol versions 2025-03-26 through 2025-11-25, where servers could send such requests on SSE streams.
• The final JSON-RPC response SHOULD terminate the stream.

​

Message Flow

​

Cancellation

​

Request Metadata

​

Protocol Version Header

​

Standard Request Headers

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
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": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
MCP-Protocol-Version: 2026-07-28
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": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

​

Custom Headers from Tool Parameters

​

Schema Extension

• MUST NOT be empty
• MUST match HTTP field-name token syntax (1*tchar, RFC 9110 Section 5.1)
• MUST NOT contain control characters, including carriage return (CR, \r) or line feed (LF, \n)
• MUST be case-insensitively unique among all x-mcp-header values in the inputSchema
• MUST only be applied to parameters with primitive types (integer, string, boolean). Parameters with type number are not permitted. Integer values MUST be within the safe range for JavaScript (−2⁵³+1 to 2⁵³−1)
• MAY be applied to properties at any nesting depth within the inputSchema, not only top-level properties

{
  "name": "execute_sql",
  "description": "Execute SQL on Google Cloud Spanner",
  "inputSchema": {
    "type": "object",
    "properties": {
      "region": {
        "type": "string",
        "description": "The region to execute the query in",
        "x-mcp-header": "Region"
      },
      "query": {
        "type": "string",
        "description": "The SQL query to execute"
      }
    },
    "required": ["region", "query"]
  }
}

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientInfo": {
        "name": "ExampleClient",
        "version": "1.0.0"
      },
      "io.modelcontextprotocol/clientCapabilities": {}
    },
    "name": "execute_sql",
    "arguments": {
      "region": "us-west1",
      "query": "SELECT * FROM users"
    }
  }
}

​

Value Encoding

• string: Use the value as-is
• integer: Convert to decimal string representation (e.g., 42, -7)
• boolean: Convert to lowercase "true" or "false"

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

​

Client Behavior

1. Extract the values for any standard headers from the request body (e.g., method, params.name, params.uri).
2. Append the Mcp-Method header and, if applicable, Mcp-Name header to the request.
3. Inspect the tool’s inputSchema for properties marked with x-mcp-header and extract the value for each parameter.
4. Encode the values according to the Value Encoding rules.
5. Append a Mcp-Param-{Name}: {Value} header to the request.

​

Server Behavior for Custom Headers

​

Case Sensitivity

​

Server Validation

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

• A required standard header (MCP-Protocol-Version, Mcp-Method, Mcp-Name) is missing.
• A header value does not match the corresponding request body value.
• A header value contains invalid characters.

​

Backward Compatibility

• If the body contains a recognized modern JSON-RPC error, the server speaks a modern version of MCP — retry using the advertised supported versions or correct the request, rather than falling back.
• If the body is empty or is not a recognized modern JSON-RPC error, fall back to initialize and continue with the legacy version for subsequent requests.

​

Earlier Streamable HTTP Revisions

• HTTP GET or DELETE to the MCP endpoint: respond with 405 Method Not Allowed.
• An Mcp-Session-Id header on a request: ignore it, and do not mint or echo session IDs.
• A Last-Event-ID header: ignore it; streams are not resumable.

​

HTTP+SSE Transport (2024-11-05)

• Continue to host both the SSE and POST endpoints of the old transport, alongside the new “MCP endpoint” defined for the Streamable HTTP transport.
  • It is also possible to combine the old POST endpoint and the new MCP endpoint, but this may introduce unneeded complexity.

1. Accept an MCP server URL from the user, which may point to either a server using the old transport or the new transport.
2. Attempt to POST a request to the server URL, with an Accept header as defined above:
   • If it succeeds, the client can assume this is a server supporting the new Streamable HTTP transport.
   • If it fails with HTTP status code 400 Bad Request, 404 Not Found, or 405 Method Not Allowed and the response body is not a recognized modern JSON-RPC error (a modern server returns one for unsupported version, unknown method, or header-validation failure):
     • Issue a GET request to the server URL, expecting that this will open an SSE stream and return an endpoint event as the first event.
     • When the endpoint event arrives, the client can assume this is a server running the old HTTP+SSE transport, and should use that transport for all subsequent communication.