MCP Initialization Headers FAQ & Answers

Step 1: Client sends 'initialize' JSON-RPC request with protocolVersion it supports. Step 2: Server responds with same or compatible version plus capabilities list (tools, resources, prompts). Step 3: If versions incompatible, client disconnects gracefully. Example request: {jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2025-03-26',capabilities:{tools:{}}}}. Server response includes: {result:{protocolVersion:'2025-03-26',capabilities:{tools:{},resources:{}}}}. After successful handshake, server advertises what it can do, client knows which features are available. This establishes foundation for all subsequent operations.

If client requests version server doesn't support, server can: (1) Respond with different version it supports, or (2) Return error. Client checks server response version - if incompatible with client's capabilities, client MUST disconnect. Example: Client supports only 2025-03-26, server responds with 2024-11-05, client disconnects. Version negotiation pattern: Client sends latest version it supports, server responds with best match. No automatic downgrade - explicit version agreement required. This prevents protocol mismatch errors during operation. Always check server response version matches client expectations.

Servers advertise capabilities in initialize response: tools (functions agent can call), resources (data agent can read), prompts (templates agent can use), roots (context boundaries). Format: {capabilities:{tools:{},resources:{listChanged:true},prompts:{},roots:{}}}. Each capability can have sub-capabilities. Example: resources.listChanged:true means server will notify when resource list changes. Clients use capabilities to know: which features available, which MCP methods to call, what to show in UI. Don't attempt using feature server didn't advertise - will fail. Check capabilities before calling tools/list, resources/list, prompts/list.

Required POST headers: (1) Content-Type: application/json - indicates JSON-RPC payload, (2) Accept: application/json, text/event-stream - client accepts both response types, (3) Mcp-Session-Id: [session-id] - required after initialization if server assigned session ID. Example: POST /mcp HTTP/1.1, Content-Type: application/json, Accept: application/json, text/event-stream, Mcp-Session-Id: uuid-here. First initialize request doesn't have session ID. Subsequent requests include session ID from server response. Missing required headers causes 400 Bad Request or protocol error.

Required GET headers for Server-Sent Events: (1) Accept: text/event-stream - client expects SSE stream, (2) Last-Event-ID: [event-id] - optional, for resuming after connection loss. Example: GET /mcp HTTP/1.1, Accept: text/event-stream, Last-Event-ID: 42. Server responds with: Content-Type: text/event-stream, stream of 'data:' prefixed JSON-RPC messages. Last-Event-ID enables resuming from specific point if connection drops - server sends events after that ID. Useful for unreliable networks. GET endpoint is read-only, used for server-initiated messages, notifications, progress updates.

Validate Origin header to prevent DNS rebinding attacks. Attacker sets up malicious domain pointing to 127.0.0.1, user visits site, JavaScript makes requests to MCP server, server sees localhost request, allows it. Solution: Check Origin header matches expected domains. Pattern: const allowedOrigins = ['https://app.example.com']; if (!allowedOrigins.includes(req.headers.origin)) return 403;. For local development: allow 'null' or localhost origins. For production: strict whitelist only. This prevents malicious websites from controlling MCP server through user's browser. Security requirement for HTTP+SSE transports. stdio transport not affected.

Streamable HTTP transport (introduced 2025-03-26 spec) REPLACED HTTP+SSE as the standard MCP transport. Uses single HTTP endpoint supporting POST and GET. Benefits: (1) Bi-directional communication over one connection, (2) Chunked Transfer-Encoding for progressive message delivery, (3) Cloud-friendly (AWS Lambda, serverless), (4) No long-lived connections required, (5) Eliminates separate endpoints for requests/responses. Session management: Server MAY assign Mcp-Session-Id in initialize response header, client includes in all subsequent requests. Pattern: Client POST to /mcp → Server streams JSON-RPC messages → Server can send notifications/requests back. Replaces HTTP+SSE polling/dual-endpoint complexity. Enterprise-friendly: works with proxies, firewalls. All new implementations should use Streamable HTTP. HTTP+SSE deprecated but supported for backwards compatibility.

Optional for first initialize request - client doesn't have session ID yet. Server assigns session ID in initialize response. Required for ALL subsequent requests after initialization. Server uses session ID to: track client state, maintain context, associate requests with session. Pattern: First request (no header) → Server responds with session ID → All following requests include Mcp-Session-Id header. If client loses session ID, must re-initialize to get new one. Missing session ID on subsequent requests causes 400 Bad Request or session not found error. Server may garbage collect sessions after timeout if no requests received.