Merge pull request modelcontextprotocol#665 from modelcontextprotocol/update-transports-docs-from-spec

Update transports documentation from specification

Author: olaservo

docs/docs/concepts/architecture.mdx

@@ -108,8 +108,8 @@ The transport layer handles the actual communication between clients and servers
    - Uses standard input/output for communication
    - Ideal for local processes
 
-2. **HTTP with SSE transport**
-   - Uses Server-Sent Events for server-to-client messages
+2. **Streamable HTTP transport**
+   - Uses HTTP with optional Server-Sent Events for streaming
    - HTTP POST for client-to-server messages
 
 All transports use [JSON-RPC](https://www.jsonrpc.org/) 2.0 to exchange messages. See the [specification](/specification/) for detailed information about the Model Context Protocol message format.
@@ -295,7 +295,7 @@ Here's a basic example of implementing an MCP server:
    - Simple process management
 
 2. **Remote communication**
-   - Use SSE for scenarios requiring HTTP compatibility
+   - Use Streamable HTTP for scenarios requiring HTTP compatibility
    - Consider security implications including authentication and authorization
 
 ### Message handling

docs/docs/concepts/transports.mdx

@@ -49,7 +49,7 @@ There are three types of JSON-RPC messages used:
 
 ## Built-in Transport Types
 
-MCP includes two standard transport implementations:
+MCP currently defines two standard transport mechanisms:
 
 ### Standard Input/Output (stdio)
 
@@ -127,7 +127,7 @@ Use stdio when:
 
 </Tabs>
 
-### Server-Sent Events (SSE)
+### Streamable HTTP
 
 <Warning>
 
@@ -139,22 +139,200 @@ and latest SDKs for the most recent information.
 
 SSE transport enables server-to-client streaming with HTTP POST requests for client-to-server communication.
 
-Use SSE when:
+Use Streamable HTTP when:
 
-- Only server-to-client streaming is needed
-- Working with restricted networks
-- Implementing simple updates
+- Building web-based integrations
+- Needing client-server communication over HTTP
+- Requiring stateful sessions
+- Supporting multiple concurrent clients
+- Implementing resumable connections
+
+#### How it Works
+
+1. **Client-to-Server Communication**: Every JSON-RPC message from client to server is sent as a new HTTP POST request to the MCP endpoint
+2. **Server Responses**: The server can respond either with:
+   - A single JSON response (`Content-Type: application/json`)
+   - An SSE stream (`Content-Type: text/event-stream`) for multiple messages
+3. **Server-to-Client Communication**: Servers can send requests/notifications to clients via:
+   - SSE streams initiated by client requests
+   - SSE streams from HTTP GET requests to the MCP endpoint
+
+<Tabs>
+  <Tab title="TypeScript (Server)">
+
+    ```typescript
+    import express from "express";
+
+    const app = express();
+
+    const server = new Server({
+      name: "example-server",
+      version: "1.0.0"
+    }, {
+      capabilities: {}
+    });
+
+    // MCP endpoint handles both POST and GET
+    app.post("/mcp", async (req, res) => {
+      // Handle JSON-RPC request
+      const response = await server.handleRequest(req.body);
+
+      // Return single response or SSE stream
+      if (needsStreaming) {
+        res.setHeader("Content-Type", "text/event-stream");
+        // Send SSE events...
+      } else {
+        res.json(response);
+      }
+    });
+
+    app.get("/mcp", (req, res) => {
+      // Optional: Support server-initiated SSE streams
+      res.setHeader("Content-Type", "text/event-stream");
+      // Send server notifications/requests...
+    });
+
+    app.listen(3000);
+    ```
+
+  </Tab>
+  <Tab title="TypeScript (Client)">
 
-#### Security Warning: DNS Rebinding Attacks
+    ```typescript
+    const client = new Client({
+      name: "example-client",
+      version: "1.0.0"
+    }, {
+      capabilities: {}
+    });
 
-SSE transports can be vulnerable to DNS rebinding attacks if not properly secured. To prevent this:
+    const transport = new HttpClientTransport(
+      new URL("http://localhost:3000/mcp")
+    );
+    await client.connect(transport);
+    ```
+
+  </Tab>
+  <Tab title="Python (Server)">
 
-1. **Always validate Origin headers** on incoming SSE connections to ensure they come from expected sources
-2. **Avoid binding servers to all network interfaces** (0.0.0.0) when running locally - bind only to localhost (127.0.0.1) instead
-3. **Implement proper authentication** for all SSE connections
+    ```python
+    from mcp.server.http import HttpServerTransport
+    from starlette.applications import Starlette
+    from starlette.routing import Route
+
+    app = Server("example-server")
+
+    async def handle_mcp(scope, receive, send):
+        if scope["method"] == "POST":
+            # Handle JSON-RPC request
+            response = await app.handle_request(request_body)
+
+            if needs_streaming:
+                # Return SSE stream
+                await send_sse_response(send, response)
+            else:
+                # Return JSON response
+                await send_json_response(send, response)
+
+        elif scope["method"] == "GET":
+            # Optional: Support server-initiated SSE streams
+            await send_sse_stream(send)
+
+    starlette_app = Starlette(
+        routes=[
+            Route("/mcp", endpoint=handle_mcp, methods=["POST", "GET"]),
+        ]
+    )
+    ```
+
+  </Tab>
+  <Tab title="Python (Client)">
+
+    ```python
+    async with http_client("http://localhost:8000/mcp") as transport:
+        async with ClientSession(transport[0], transport[1]) as session:
+            await session.initialize()
+    ```
+
+  </Tab>
+
+</Tabs>
+
+#### Session Management
+
+Streamable HTTP supports stateful sessions to maintain context across multiple requests:
+
+1. **Session Initialization**: Servers may assign a session ID during initialization by including it in an `Mcp-Session-Id` header
+2. **Session Persistence**: Clients must include the session ID in all subsequent requests using the `Mcp-Session-Id` header
+3. **Session Termination**: Sessions can be explicitly terminated by sending an HTTP DELETE request with the session ID
+
+Example session flow:
+
+```typescript
+// Server assigns session ID during initialization
+app.post("/mcp", (req, res) => {
+  if (req.body.method === "initialize") {
+    const sessionId = generateSecureId();
+    res.setHeader("Mcp-Session-Id", sessionId);
+    // Store session state...
+  }
+  // Handle request...
+});
+
+// Client includes session ID in subsequent requests
+fetch("/mcp", {
+  method: "POST",
+  headers: {
+    "Content-Type": "application/json",
+    "Mcp-Session-Id": sessionId,
+  },
+  body: JSON.stringify(request),
+});
+```
+
+#### Resumability and Redelivery
+
+To support resuming broken connections, Streamable HTTP provides:
+
+1. **Event IDs**: Servers can attach unique IDs to SSE events for tracking
+2. **Resume from Last Event**: Clients can resume by sending the `Last-Event-ID` header
+3. **Message Replay**: Servers can replay missed messages from the disconnection point
+
+This ensures reliable message delivery even with unstable network connections.
+
+#### Security Considerations
+
+When implementing Streamable HTTP transport, follow these security best practices:
+
+1. **Validate Origin Headers**: Always validate the `Origin` header on all incoming connections to prevent DNS rebinding attacks
+2. **Bind to Localhost**: When running locally, bind only to localhost (127.0.0.1) rather than all network interfaces (0.0.0.0)
+3. **Implement Authentication**: Use proper authentication for all connections
+4. **Use HTTPS**: Always use TLS/HTTPS for production deployments
+5. **Validate Session IDs**: Ensure session IDs are cryptographically secure and properly validated
 
 Without these protections, attackers could use DNS rebinding to interact with local MCP servers from remote websites.
 
+### Server-Sent Events (SSE) - Deprecated
+
+<Note>
+  SSE as a standalone transport is deprecated as of protocol version 2024-11-05.
+  It has been replaced by Streamable HTTP, which incorporates SSE as an optional
+  streaming mechanism. For backwards compatibility information, see the
+  [backwards compatibility](#backwards-compatibility) section below.
+</Note>
+
+The legacy SSE transport enabled server-to-client streaming with HTTP POST requests for client-to-server communication.
+
+Previously used when:
+
+- Only server-to-client streaming is needed
+- Working with restricted networks
+- Implementing simple updates
+
+#### Legacy Security Considerations
+
+The deprecated SSE transport had similar security considerations to Streamable HTTP, particularly regarding DNS rebinding attacks. These same protections should be applied when using SSE streams within the Streamable HTTP transport.
+
 <Tabs>
   <Tab title="TypeScript (Server)">
 
@@ -437,8 +615,8 @@ When implementing transport:
 - Handle denial of service scenarios
 - Monitor for unusual patterns
 - Implement proper firewall rules
-- For SSE transports, validate Origin headers to prevent DNS rebinding attacks
-- For local SSE servers, bind only to localhost (127.0.0.1) instead of all interfaces (0.0.0.0)
+- For HTTP-based transports (including Streamable HTTP), validate Origin headers to prevent DNS rebinding attacks
+- For local servers, bind only to localhost (127.0.0.1) instead of all interfaces (0.0.0.0)
 
 ## Debugging Transport
 
@@ -454,3 +632,65 @@ Tips for debugging transport issues:
 8. Monitor resource usage
 9. Test edge cases
 10. Use proper error tracking
+
+## Backwards Compatibility
+
+To maintain compatibility between different protocol versions:
+
+### For Servers Supporting Older Clients
+
+Servers wanting to support clients using the deprecated HTTP+SSE transport should:
+
+1. Host both the old SSE and POST endpoints alongside the new MCP endpoint
+2. Handle initialization requests on both endpoints
+3. Maintain separate handling logic for each transport type
+
+### For Clients Supporting Older Servers
+
+Clients wanting to support servers using the deprecated transport should:
+
+1. Accept server URLs that may use either transport
+2. Attempt to POST an `InitializeRequest` with proper `Accept` headers:
+   - If successful, use Streamable HTTP transport
+   - If it fails with 4xx status, fall back to legacy SSE transport
+3. Issue a GET request expecting an SSE stream with `endpoint` event for legacy servers
+
+Example compatibility detection:
+
+```typescript
+async function detectTransport(serverUrl: string): Promise<TransportType> {
+  try {
+    // Try Streamable HTTP first
+    const response = await fetch(serverUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json, text/event-stream",
+      },
+      body: JSON.stringify({
+        jsonrpc: "2.0",
+        method: "initialize",
+        params: {
+          /* ... */
+        },
+      }),
+    });
+
+    if (response.ok) {
+      return "streamable-http";
+    }
+  } catch (error) {
+    // Fall back to legacy SSE
+    const sseResponse = await fetch(serverUrl, {
+      method: "GET",
+      headers: { Accept: "text/event-stream" },
+    });
+
+    if (sseResponse.ok) {
+      return "legacy-sse";
+    }
+  }
+
+  throw new Error("Unsupported transport");
+}
+```