Transports

Documentation Index

Fetch the complete documentation index at: https://modelcontextprotocol.io/llms.txt

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

1. stdio, communication over standard in and standard out
2. Streamable HTTP

​

stdio

• The client launches the MCP server as a subprocess.
• The server reads JSON-RPC messages from its standard input (stdin) and sends messages to its standard output (stdout).
• Messages are individual JSON-RPC requests, notifications, or responses.
• Messages are delimited by newlines, and MUST NOT contain embedded newlines.
• The server MAY write UTF-8 strings to its standard error (stderr) for any logging purposes including informational, debug, and error messages.
• The client MAY capture, forward, or ignore the server’s stderr output and SHOULD NOT assume stderr output indicates error conditions.
• The server MUST NOT write anything to its stdout that is not a valid MCP message.
• The client MUST NOT write anything to the server’s stdin that is not a valid MCP message.

​

Streamable HTTP

​

Security Warning

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 to the Server

1. The client MUST use HTTP POST to send JSON-RPC messages to the MCP endpoint.
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 standard MCP request headers on each POST request.
4. The body of the HTTP POST request MUST be a single JSON-RPC request, notification, or response to a server-sent request.
5. If the body is a JSON-RPC notification or response to a server-sent request:
   • If the server accepts the input, the server MUST return HTTP status code 202 Accepted with no body.
   • If the server cannot accept the input, 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 either return Content-Type: text/event-stream, to initiate an SSE stream, or Content-Type: application/json, to return one JSON object. The client MUST support both these cases.
7. If the server initiates an SSE stream:
   • The server SHOULD immediately send an SSE event consisting of an event ID and an empty data field in order to prime the client to reconnect (using that event ID as Last-Event-ID).
   • After the server has sent an SSE event with an event ID to the client, the server MAY close the connection (without terminating the SSE stream) at any time in order to avoid holding a long-lived connection. The client SHOULD then “poll” the SSE stream by attempting to reconnect.
   • If the server does close the connection prior to terminating the SSE stream, it SHOULD send an SSE event with a standard retry field before closing the connection. The client MUST respect the retry field, waiting the given number of milliseconds before attempting to reconnect.
   • The SSE stream SHOULD eventually include a JSON-RPC response for the JSON-RPC request sent in the POST body.
   • The server MAY send JSON-RPC requests and notifications before sending the JSON-RPC response. These messages MUST relate to the originating client request.
   • After the JSON-RPC response has been sent, the server SHOULD terminate the SSE stream.
   • Disconnection MAY occur at any time (e.g., due to network conditions). Therefore:
     • Disconnection SHOULD NOT be interpreted as the client cancelling its request.
     • To cancel, the client SHOULD explicitly send an MCP CancelledNotification.
     • To avoid message loss due to disconnection, the server MAY make the stream resumable.

​

Listening for Messages from the Server

1. The client MAY issue an HTTP GET to the MCP endpoint. This can be used to open an SSE stream, allowing the server to communicate to the client, without the client first sending data via HTTP POST.
2. The client MUST include an Accept header, listing text/event-stream as a supported content type.
3. The server MUST either return Content-Type: text/event-stream in response to this HTTP GET, or else return HTTP 405 Method Not Allowed, indicating that the server does not offer an SSE stream at this endpoint. Per RFC 9110 §15.5.6, if the server returns HTTP 405, it MUST include an Allow header listing the methods it does support (e.g., Allow: POST).
4. If the server initiates an SSE stream:
   • The server MAY send JSON-RPC notifications and pings on the stream.
   • These messages SHOULD be unrelated to any concurrently-running JSON-RPC request from the client, except that roots/list, sampling/createMessage, and elicitation/create requests MUST NOT be sent on standalone streams.
   • The server MUST NOT send a JSON-RPC response on the stream unless resuming a stream associated with a previous client request.
   • The server MAY close the SSE stream at any time.
   • If the server closes the connection without terminating the stream, it SHOULD follow the same polling behavior as described for POST requests: sending a retry field and allowing the client to reconnect.
   • The client MAY close the SSE stream at any time.

​

Multiple Connections

1. The client MAY remain connected to multiple SSE streams simultaneously.
2. The server MUST send each of its JSON-RPC messages on only one of the connected streams; that is, it MUST NOT broadcast the same message across multiple streams.
   • The risk of message loss MAY be mitigated by making the stream resumable.

​

Resumability and Redelivery

1. Servers MAY attach an id field to their SSE events, as described in the SSE standard.
   • If present, the ID MUST be globally unique across all streams.
   • Event IDs SHOULD encode sufficient information to identify the originating stream, enabling the server to correlate a Last-Event-ID to the correct stream.
2. If the client wishes to resume after a disconnection (whether due to network failure or server-initiated closure), it SHOULD issue an HTTP GET to the MCP endpoint, and include the Last-Event-ID header to indicate the last event ID it received.
   • The server MAY use this header to replay messages that would have been sent after the last event ID, on the stream that was disconnected, and to resume the stream from that point.
   • The server MUST NOT replay messages that would have been delivered on a different stream.
   • This mechanism applies regardless of how the original stream was initiated (via POST or GET). Resumption is always via HTTP GET with Last-Event-ID.

​

Sequence Diagram

​

Protocol Version Header

​

Standard MCP Request Headers

​

Examples

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Method: tools/call
Mcp-Name: get_weather

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": {
      "location": "Seattle, WA"
    }
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
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"
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Method: initialize

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

POST /mcp HTTP/1.1
Content-Type: application/json
Mcp-Method: notifications/initialized

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

​

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-Method, Mcp-Name) is missing
• A header value does not match the corresponding request body value
• A header value contains invalid characters

​

Custom Headers from Tool Parameters

​

Schema Extension

• MUST NOT be empty
• MUST contain only ASCII characters (excluding space and :)
• MUST be case-insensitively unique among all x-mcp-header values in the inputSchema
• MUST only be applied to parameters with primitive types (number, string, boolean)

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

​

Value Encoding

• string: Use the value as-is
• number: Convert to decimal string representation (e.g., 42, 3.14)
• 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

​

SSE Stream Configuration

​

Backwards Compatibility

• 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 an InitializeRequest 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 the following HTTP status codes “400 Bad Request”, “404 Not Found”, or “405 Method Not Allowed”:
     • 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.

​

Custom Transports