You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A client that implements backwards compatibility according to the [MCP specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility), allowing it to work with both new and legacy servers. This client demonstrates:
13
39
14
-
## Streamable HTTP - single node deployment with basic session state management
40
+
- The client first POSTs an initialize request to the server URL:
41
+
- If successful, it uses the Streamable HTTP transport
42
+
- If it fails with a 4xx status, it attempts a GET request to establish an SSE stream
15
43
16
-
Multi node with state management example will be added soon after we add support.
### Server supporting SSE via GET (`server/standaloneSseWithGetStreamableHttp.ts`)
87
+
A server that demonstrates server notifications using Streamable HTTP.
36
88
37
-
An MCP server that demonstrates how to support SSE notifications via GET requests using the Streamable HTTP transport with Express. The server dynamically adds resources at regular intervals and supports notifications for resource list changes (server notifications are available through the standalone SSE connection established by GET request).
89
+
- Resource list change notifications with dynamically added resources
The server will start on port 3000 and automatically create new resources every 5 seconds.
97
+
#### Deprecated SSE Transport
46
98
47
-
### Server with JSON response mode (`server/jsonResponseStreamableHttp.ts`)
99
+
A server that implements the deprecated HTTP+SSE transport (protocol version 2024-11-05). This example only used for testing backwards compatibility for clients.
100
+
101
+
- Two separate endpoints: `/mcp` for the SSE stream (GET) and `/messages` for client messages (POST)
102
+
- Tool implementation with a `start-notification-stream` tool that demonstrates sending periodic notifications
103
+
104
+
```bash
105
+
npx tsx src/examples/server/simpleSseServer.ts
106
+
```
48
107
49
-
A simple MCP server that uses the Streamable HTTP transport with JSON response mode enabled, implemented with Express. The server provides a simple `greet` tool that returns a greeting for a name.
108
+
#### Streamable Http Backwards Compatible Server with SSE
50
109
51
-
_NOTE: This demonstrates a server that does not use SSE at all. Note that this limits its support for MCP features; for example, it cannot provide logging and progress notifications for tool execution._
110
+
A server that supports both Streamable HTTP and SSE transports, adhering to the [MCP specification for backwards compatibility](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#backwards-compatibility).
52
111
53
-
#### Running the server
112
+
- Single MCP server instance with multiple transport options
113
+
- Support for Streamable HTTP requests at `/mcp` endpoint (GET/POST/DELETE)
114
+
- Support for deprecated SSE transport with `/sse` (GET) and `/messages` (POST)
115
+
- Session type tracking to avoid mixing transport types
116
+
- Notifications and tool execution across both transport types
When deploying MCP servers in a horizontally scaled environment (multiple server instances), there are a few different options that can be useful for different use cases:
125
+
-**Stateless mode** - No need to maintain state between calls to MCP servers. Useful for simple API wrapper servers.
126
+
-**Persistent storage mode** - No local state needed, but session data is stored in a database. Example: an MCP server for online ordering where the shopping cart is stored in a database.
127
+
-**Local state with message routing** - Local state is needed, and all requests for a session must be routed to the correct node. This can be done with a message queue and pub/sub system.
61
128
62
-
A client that connects to the server, initializes it, and demonstrates how to:
129
+
#### Stateless Mode
63
130
64
-
- List available tools and call the `greet` tool
65
-
- List available prompts and get the `greeting-template` prompt
66
-
- List available resources
131
+
The Streamable HTTP transport can be configured to operate without tracking sessions. This is perfect for simple API proxies or when each request is completely independent.
For cases where you need session continuity but don't need to maintain in-memory state on specific nodes, you can use a database to persist session data while still allowing any node to handle requests.
170
+
171
+
##### Implementation
172
+
173
+
Configure the transport with session management, but retrieve and store all state in an external persistent storage:
174
+
175
+
```typescript
176
+
sessionIdGenerator: () =>randomUUID(),
177
+
eventStore: databaseEventStore
104
178
```
105
-
Once a session is established, we can send POST requests:
106
179
107
-
#### List tools
108
-
```bash
109
-
# Then list tools using the saved session ID
110
-
curl -X POST -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream"\
All session state is stored in the database, and any node can serve any client by retrieving the state when needed.
181
+
182
+
- Maintains sessions with unique IDs
183
+
- Stores all session data in an external database
184
+
- Provides resumability through the database-backed EventStore
185
+
- Any node can handle any request for the same session
186
+
- No node-specific memory state means no need for message routing
187
+
- Good for applications where state can be fully externalized
188
+
- Somewhat higher latency due to database access for each request
189
+
190
+
191
+
```
192
+
┌─────────────────────────────────────────────┐
193
+
│ Client │
194
+
└─────────────────────────────────────────────┘
195
+
│
196
+
▼
197
+
┌─────────────────────────────────────────────┐
198
+
│ Load Balancer │
199
+
└─────────────────────────────────────────────┘
200
+
│ │
201
+
▼ ▼
202
+
┌─────────────────┐ ┌─────────────────────┐
203
+
│ MCP Server #1 │ │ MCP Server #2 │
204
+
│ (Node.js) │ │ (Node.js) │
205
+
└─────────────────┘ └─────────────────────┘
206
+
│ │
207
+
│ │
208
+
▼ ▼
209
+
┌─────────────────────────────────────────────┐
210
+
│ Database (PostgreSQL) │
211
+
│ │
212
+
│ • Session state │
213
+
│ • Event storage for resumability │
214
+
└─────────────────────────────────────────────┘
114
215
```
115
216
116
-
#### Call tool
117
217
118
-
```bash
119
-
# Call the greet tool using the saved session ID
120
-
curl -X POST \
121
-
-H "Content-Type: application/json"\
122
-
-H "Accept: application/json"\
123
-
-H "Accept: text/event-stream"\
124
-
-H "mcp-session-id: $SESSION_ID"\
125
-
-d '{
126
-
"jsonrpc": "2.0",
127
-
"method": "tools/call",
128
-
"params": {
129
-
"name": "greet",
130
-
"arguments": {
131
-
"name": "World"
132
-
}
133
-
},
134
-
"id": "2"
135
-
}' \
136
-
http://localhost:3000/mcp
218
+
219
+
#### Streamable HTTP with Distributed Message Routing
220
+
221
+
For scenarios where local in-memory state must be maintained on specific nodes (such as Computer Use or complex session state), the Streamable HTTP transport can be combined with a pub/sub system to route messages to the correct node handling each session.
222
+
223
+
1.**Bidirectional Message Queue Integration**:
224
+
- All nodes both publish to and subscribe from the message queue
225
+
- Each node registers the sessions it's actively handling
226
+
- Messages are routed based on session ownership
227
+
228
+
2.**Request Handling Flow**:
229
+
- When a client connects to Node A with an existing `mcp-session-id`
230
+
- If Node A doesn't own this session, it:
231
+
- Establishes and maintains the SSE connection with the client
232
+
- Publishes the request to the message queue with the session ID
233
+
- Node B (which owns the session) receives the request from the queue
234
+
- Node B processes the request with its local session state
235
+
- Node B publishes responses/notifications back to the queue
236
+
- Node A subscribes to the response channel and forwards to the client
237
+
238
+
3.**Channel Identification**:
239
+
- Each message channel combines both `mcp-session-id` and `stream-id`
240
+
- This ensures responses are correctly routed back to the originating connection
241
+
242
+
```
243
+
┌─────────────────────────────────────────────┐
244
+
│ Client │
245
+
└─────────────────────────────────────────────┘
246
+
│
247
+
▼
248
+
┌─────────────────────────────────────────────┐
249
+
│ Load Balancer │
250
+
└─────────────────────────────────────────────┘
251
+
│ │
252
+
▼ ▼
253
+
┌─────────────────┐ ┌─────────────────────┐
254
+
│ MCP Server #1 │◄───►│ MCP Server #2 │
255
+
│ (Has Session A) │ │ (Has Session B) │
256
+
└─────────────────┘ └─────────────────────┘
257
+
▲│ ▲│
258
+
│▼ │▼
259
+
┌─────────────────────────────────────────────┐
260
+
│ Message Queue / Pub-Sub │
261
+
│ │
262
+
│ • Session ownership registry │
263
+
│ • Bidirectional message routing │
264
+
│ • Request/response forwarding │
265
+
└─────────────────────────────────────────────┘
137
266
```
267
+
268
+
269
+
- Maintains session affinity for stateful operations without client redirection
270
+
- Enables horizontal scaling while preserving complex in-memory state
271
+
- Provides fault tolerance through the message queue as intermediary
272
+
273
+
274
+
## Backwards Compatibility
275
+
276
+
### Testing Streamable HTTP Backwards Compatibility with SSE
277
+
278
+
To test the backwards compatibility features:
279
+
280
+
1. Start one of the server implementations:
281
+
```bash
282
+
# Legacy SSE server (protocol version 2024-11-05)
283
+
npx tsx src/examples/server/simpleSseServer.ts
284
+
285
+
# Streamable HTTP server (protocol version 2025-03-26)
0 commit comments