MCP 服务器

github-repo-stats

A Model Context Protocol server that fetches public GitHub repository statistics.

README

mcp-transport-talk

Code companion for my MCP Dev Summit Bengaluru 2026 talk: "From SSE to Streamable HTTP: What Actually Changed in MCP's Transport Layer and Why Your Servers Need to Catch Up"

— Animesh Pathak (@sonichigo), Developer Relations Engineer, Harness Inc

A note on terminology (important — read this first)

The talk title uses community shorthand. People say "SSE → Streamable HTTP" when what they actually mean is "the dual-endpoint HTTP+SSE architecture → the single-endpoint Streamable HTTP architecture."

Three things people conflate:

Term	What it is	Status
HTTP+SSE transport	The deprecated MCP transport. Two endpoints: `GET /sse` (persistent) + `POST /message`. Required sticky sessions.	Deprecated (spec 2025-03-26)
Streamable HTTP transport	The current MCP transport. Single endpoint that supports both POST and GET, with optional SSE streaming for responses.	Current spec
SSE (the format)	The W3C `text/event-stream` content type. Used inside Streamable HTTP for streaming server messages.	Still alive — actively used

The deprecation was architectural, not protocol-level. Streamable HTTP still uses SSE format when it needs to stream multiple messages — it's just no longer a separate persistent endpoint. Throughout this repo, when I use the shorthand "SSE deprecated" I mean the two-endpoint architecture.

What's in here

The same MCP server (a GitHub repo stats tool) implemented three ways. You can run them side by side and watch how each architecture behaves under different conditions.

src/
├── stdio-server/                       # Local-only transport (still recommended for Claude Desktop / Code)
├── http-sse-server-deprecated/         # The dual-endpoint HTTP+SSE pattern (deprecated March 2025)
└── streamable-http-server/             # The current spec (uses SSE format internally when streaming)

clients/                                # A minimal MCP client to test each server
scripts/
├── load-test-dual-endpoint.sh          # Watch the deprecated architecture break behind a load balancer
└── load-test-streamable.sh             # Watch Streamable HTTP scale horizontally

The tool we're implementing

A single MCP tool — github_repo_stats — that fetches public stats for any GitHub repo. Picked deliberately:

Real I/O (calls the GitHub API), so transport behavior is observable.
Stateless (no auth, no session needed), so we can fairly compare architectures.
Small enough to fit on a slide.

Quick start

pnpm install

# Run all three servers in parallel
pnpm dev:all

# Or one at a time:
pnpm dev:stdio          # → connects via stdin/stdout
pnpm dev:http-sse       # → http://localhost:3001 (deprecated dual-endpoint pattern)
pnpm dev:streamable     # → http://localhost:3002 (current spec)

The demo that lands the point

# Start the load-balancer simulator (round-robin across 3 instances of each server)
pnpm demo:lb

# Hit the dual-endpoint server through it — watch it fail intermittently
pnpm demo:lb:dual-endpoint

# Hit the Streamable HTTP server through it — watch it just work
pnpm demo:lb:streamable

The deprecated dual-endpoint server fails roughly 2 out of every 3 requests because the POST /message lands on a different process than the GET /sse that initiated the session. The Streamable HTTP server is stateless and doesn't care which instance handles each request.

This is the live version of the architectural contrast in the slides.

The real-world failure I keep referencing

The intermittent-failure scenario in scripts/load-test-dual-endpoint.sh is a synthetic version of an actual incident from the Harness MCP Server's staging environment. We had a load balancer with default round-robin behavior in front of three pods. About 60% of MCP tool calls failed silently because the POST request landed on the wrong pod. Logs showed nothing because each pod treated it as a missing session and returned 404 to the SSE stream that wasn't there.

Three days of debugging produced a one-line architectural fix: switch transports. That experience is what this talk is built on.

Where SSE format still lives in the current architecture

This is the bit that confuses people. The current Streamable HTTP transport still uses SSE format — but as a response mode, not a separate endpoint. When a client POSTs to the single /mcp endpoint, the server can respond with either:

A plain JSON body (Content-Type: application/json) — for simple one-shot requests
An SSE stream (Content-Type: text/event-stream) — when the server needs to stream progress, notifications, or multiple messages

See src/streamable-http-server/index.ts — the SDK's handleRequest() picks the response mode automatically based on what the server is doing.

Migration cheat sheet

If you have an existing dual-endpoint server and want to migrate, the diff is roughly:

- import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

- app.get("/sse", async (req, res) => {
-   const transport = new SSEServerTransport("/message", res);
-   await server.connect(transport);
- });
- app.post("/message", async (req, res) => {
-   await transport.handlePostMessage(req, res);
- });

+ app.post("/mcp", async (req, res) => {
+   const transport = new StreamableHTTPServerTransport({
+     sessionIdGenerator: () => randomUUID(),
+   });
+   await server.connect(transport);
+   await transport.handleRequest(req, res, req.body);
+ });