Message Framing

The default and most common framing method for Stdio Transport. Each complete JSON-RPC message (request, response, or notification) is terminated by a newline character (\n).

• Mechanism: The sender writes a JSON string followed by \n to stdout; the receiver reads from stdin until a newline is encountered.
• Advantages: Simple, universally supported, and easy to debug. It's the standard for command-line tool integration.
• Example: A tool invocation message would be sent as {"jsonrpc": "2.0", "method": "tools/call", ...}\n.

The framing method used for SSE Transport, which is based on the W3C Server-Sent Events standard. It's designed for long-lived HTTP connections where the server can push messages asynchronously.

• Mechanism: Messages are formatted as SSE events. Each JSON-RPC message is sent as a separate event, with the data field containing the JSON string: data: {\"jsonrpc\": \"2.0\", ...}\n\n.
• Advantages: Enables real-time, push-based communication from server to client over HTTP, ideal for web-based or remote MCP servers.
• Consideration: Requires the client to handle HTTP connection management and event stream parsing.

A framing method that prefixes each message with a header specifying its exact byte length. This is a common alternative in binary or socket-based protocols.

• Mechanism: A message is framed as Content-Length: <N>\r\n\r\n<JSON Body>. The receiver reads the header, extracts the length N, then reads exactly N bytes for the payload.
• Advantages: Allows for arbitrary content within the message body, including newline characters, without risking parse errors. Provides explicit message boundaries.
• Usage: While not the primary MCP method, it's a well-known pattern in protocols like the Language Server Protocol (LSP) and can be implemented for custom transports.

A special framing case where multiple JSON-RPC requests or responses are combined into a single JSON array and sent as one framed unit.

• Mechanism: An array of JSON-RPC message objects is constructed and then framed using the transport's standard method (e.g., NDJSON). The receiver parses the array and processes each message sequentially.
• Advantages: Can reduce overhead in high-throughput scenarios by amortizing the transport framing cost across multiple messages.
• Consideration: The entire batch must be successfully parsed; an error in one message can complicate the handling of the entire batch. Not all MCP clients or servers may support batch operations.

A key architectural principle of MCP is the separation between the message format (JSON-RPC) and the framing method. This allows the protocol to adapt to different environments.

• Core Protocol: Defines the JSON-RPC structures for tools/call, resources/read, etc.
• Framing Adapter: A thin layer responsible for encoding/decoding these structures according to the transport's rules (adding \n, SSE data: prefixes, etc.).
• Benefit: An MCP server written for stdio can be adapted to SSE primarily by changing its framing layer, not its core logic. This promotes code reuse and flexibility.

Robust MCP implementations must handle framing-related errors gracefully to maintain stability.

• Common Errors: Malformed JSON, incorrect length headers, missing newline terminators, or SSE stream disconnections.
• Resilience Patterns:
  • Validation: Parse and validate JSON structure immediately after deframing.
  • Timeouts: Implement read/write timeouts to prevent hanging on partial messages.
  • Reconnection: For stateful transports like SSE, implement automatic reconnection logic with backoff.
  • Logging: Log framing errors with enough context (partial payload) to aid debugging, but avoid exposing sensitive data.

An MCP Transport is the concrete communication layer that carries framed JSON-RPC messages between a client and server. Framing rules are specific to the chosen transport.

• Defines Framing Method: The transport dictates how messages are delimited (e.g., newline-separated for stdio, event stream format for SSE).
• Common Transports: Stdio Transport (for local processes), SSE Transport (for HTTP-based servers), and named pipes.
• Abstraction Layer: Message Framing operates at this layer, insulating the JSON-RPC logic from the raw byte stream details.

Stdio Transport is an MCP transport where the client and server communicate over standard input and output streams. Its framing rule is simple and critical.

• Framing Rule: Messages are delimited by a newline character (\n). Each JSON-RPC message must be a single line.
• Use Case: Ideal for integrating with local scripts, command-line tools, and processes spawned by the client.
• Parsing Requirement: The receiver must read the input stream until a newline is encountered, then parse the complete line as a JSON object.

A Message Delimiter is the specific character or sequence used to signal the boundary between consecutive messages in a stream. It is the operational essence of framing.

• Primary Function: Allows a parser to know where one complete message ends and the next begins in a continuous byte stream.
• Examples: The newline (\n) in stdio, the \n\n sequence following an SSE data: line, or a length prefix in other protocols.
• Robustness: Choosing a delimiter that cannot appear within a valid JSON message (like a newline within a string) is crucial for reliable parsing.

Stream Parsing is the client/server activity of reading an input stream, applying the framing rules, and reconstructing discrete JSON-RPC messages for processing.

• Stateful Process: The parser must buffer incoming data until a complete message (as defined by the delimiter) is received.
• Error Handling: Must manage malformed JSON, incomplete messages, and protocol violations.
• Implementation: A core, low-level component of any MCP client or server library that handles the raw transport connection.