Multi-Client SSE Remote Connections in MCP

Multi-Client SSE Remote Connections in MCP

The standard input and output (stdio) transport mechanism is the standard configuration for local developer workstations. Spawning a local sub-process over piped standard streams is simple, fast, and secure. However, stdio architectures break down when organizations attempt to centralize expensive tools—such as Kubernetes cluster monitors, private database query runners, or enterprise security scanners—behind shared remote network gateways.

The Model Context Protocol (MCP) specifies Server-Sent Events (SSE) as the primary networking transport for remote client-server topologies. Operating over standard HTTP/1.1 and HTTP/2 infrastructures, SSE provides an asynchronous, unidirectional text stream from server to client, paired with correlated HTTP POST endpoints for client-to-server messaging. This architecture enables multiple developer agents in Claude Desktop, Cursor, and custom browser dashboards to concurrently share centralized MCP servers without local process overhead.

1. Problem Statement and Architecture

Transitioning from local child processes to multi-client remote networks introduces distinct architectural challenges:

1. ▸State Isolation and Multiplexing: If multiple agents connect to a single HTTP service, tool requests and notifications must not leak between developer sessions. The server must maintain isolated session contexts for each connecting client.
2. ▸Reverse Proxy Buffering: Enterprise ingress controllers (Nginx, AWS ALB, Cloudflare) default to buffering HTTP response chunks to optimize TCP packets. This buffering destroys real-time streaming, causing JSON-RPC responses to stall until buffers fill.
3. ▸Cross-Origin Resource Sharing (CORS): Browser-based agent environments running on different domains require rigorous preflight header negotiations to prevent unauthorized cross-site requests.

+-----------------------------------------------------------------------------------+
|                              Multi-Client Architecture                            |
|                                                                                   |
|  +--------------------+   HTTP GET /sse?sessionId=123 (Stream)   +-------------+  |
|  | Developer 1 Agent  | <======================================  |             |  |
|  | (Claude Desktop)   |  --- HTTP POST /message?sessionId=123 -> |             |  |
|  +--------------------+                                          | Remote MCP  |  |
|                                                                  | SSE Gateway |  |
|  +--------------------+   HTTP GET /sse?sessionId=456 (Stream)   | (Express /  |  |
|  | Developer 2 Agent  | <======================================  |  Fastify)   |  |
|  | (Cursor IDE)       |  --- HTTP POST /message?sessionId=456 -> |             |  |
|  +--------------------+                                          +-------------+  |
+-----------------------------------------------------------------------------------+

In an SSE-based MCP topology, the client opens a persistent GET connection to the server's streaming endpoint. The server assigns a unique sessionId, instantiates a dedicated SSEServerTransport, and begins streaming SSE events. When the agent issues a JSON-RPC method, it posts the payload to the correlated message endpoint.

2. Prerequisites and Environment Matrix

Implementing an SSE-based MCP server requires Node.js 18 or later and the official @modelcontextprotocol/sdk.

Install required project dependencies:

npm install @modelcontextprotocol/sdk express cors uuid
npm install -D typescript @types/express @types/cors @types/uuid @types/node

3. Multi-Session SSE Server Implementation

Below is a complete, production-ready TypeScript implementation of an SSE-based MCP server supporting concurrent multi-client sessions with strict isolation.

import express, { Request, Response } from "express";
import cors from "cors";
import { v4 as uuidv4 } from "uuid";
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

const app = express();
app.use(cors({ origin: true, credentials: true }));

// Store active transport sessions by ID
const activeSessions = new Map<string, { transport: SSEServerTransport; server: Server }>();

function createMcpServerInstance(sessionId: string): Server {
  const server = new Server(
    { name: `remote-cluster-gateway-${sessionId}`, version: "1.0.0" },
    { capabilities: { tools: {} } }
  );

  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: "get_cluster_status",
        description: "Retrieve real-time health metrics for the shared microservice cluster.",
        inputSchema: { type: "object", properties: {} }
      }
    ]
  }));

  server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name === "get_cluster_status") {
      return {
        content: [{ type: "text", text: `Cluster healthy. Session: ${sessionId}. Uptime: 99.98%` }]
      };
    }
    throw new Error("Tool not recognized");
  });

  return server;
}

// SSE Connection Endpoint
app.get("/sse", async (req: Request, res: Response) => {
  const sessionId = uuidv4();
  
  // Disable proxy response buffering
  res.setHeader("Content-Type", "text/event-stream");
  res.setHeader("Cache-Control", "no-cache");
  res.setHeader("Connection", "keep-alive");
  res.setHeader("X-Accel-Buffering", "no");

  const transport = new SSEServerTransport(`/message?sessionId=${sessionId}`, res);
  const server = createMcpServerInstance(sessionId);

  activeSessions.set(sessionId, { transport, server });

  req.on("close", () => {
    activeSessions.delete(sessionId);
    console.log(`Session closed and pruned: ${sessionId}`);
  });

  await server.connect(transport);
  console.log(`New SSE client connected with session ID: ${sessionId}`);
});

// JSON-RPC Message Handling Endpoint
app.post("/message", express.json(), async (req: Request, res: Response) => {
  const sessionId = req.query.sessionId as string;
  const session = activeSessions.get(sessionId);

  if (!session) {
    res.status(404).send("Session expired or invalid.");
    return;
  }

  await session.transport.handlePostMessage(req, res);
});

const PORT = process.env.PORT || 3001;
app.listen(PORT, () => {
  console.log(`Multi-client SSE MCP Server listening on port ${PORT}`);
});

4. Multi-Host Configuration Snippets

Clients connect to remote SSE servers by specifying the HTTP endpoint rather than a local executable path.

Claude Desktop

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "remote-cluster": {
      "endpoint": "https://mcp.internal.example.com/sse"
    }
  }
}

Cursor IDE

In .cursor/mcp.json:

{
  "mcpServers": {
    "remote-cluster": {
      "endpoint": "https://mcp.internal.example.com/sse"
    }
  }
}

OpenAI Codex CLI

In ~/.codex/config.toml:

[mcp_servers.remote_cluster]
url = "https://mcp.internal.example.com/sse"

5. Common Errors and Production Troubleshooting

1. Silent Freezes via Proxy Buffering (Nginx / Cloudflare)

• ▸Symptom: The client connects to /sse, but tool invocations hang indefinitely without returning output.
• ▸Root Cause: The reverse proxy buffers HTTP chunks until reaching its buffer threshold (typically 4 KB or 8 KB).
• ▸Solution: Configure your reverse proxy to disable response buffering explicitly. In Nginx:

location /sse {
    proxy_pass ;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_cache off;
    chunked_transfer_encoding off;
}

2. Session Leakage and Memory Bloat

• ▸Symptom: Server memory usage rises steadily over days of usage until an OOM crash occurs.
• ▸Root Cause: Abruptly severed client connections fail to trigger socket cleanup, leaving orphaned transport objects in memory.
• ▸Solution: Listen to the HTTP request close event on the /sse route to unregister session state, and implement periodic heartbeat timeouts that prune idle sessions exceeding 15 minutes of inactivity.

3. HTTP 400 Bad Request on Preflight Checks

• ▸Symptom: Browser-based agent tools report CORS header 'Access-Control-Allow-Origin' missing.
• ▸Root Cause: The /message endpoint failed to answer the browser's preflight OPTIONS request.
• ▸Solution: Ensure your Express CORS middleware is applied globally at the top of the middleware stack prior to route definitions.

6. External Citations and Security Guardrails

Deploying network-facing MCP gateways requires rigorous zero-trust protections:

1. ▸Mutual TLS or Bearer Authentication: Never expose unauthenticated SSE endpoints to public networks. Enforce Bearer token verification on both the /sse registration and /message post routes.
2. ▸Rate Limiting: Apply token bucket rate limiting (e.g., express-rate-limit) to prevent individual clients from monopolizing server capacity.
3. ▸Session ID Cryptography: Always generate cryptographically secure UUIDv4 session tokens to prevent session hijacking.

• ▸npm @modelcontextprotocol/sdk Registry (opens in a new tab)
• ▸Official Model Context Protocol Architecture Documentation (opens in a new tab)
• ▸MDN Server-Sent Events Specification (opens in a new tab)