feat(examples): add SSE transport support and shared server utility

[ochafik]

Summary

• Add SSE transport backwards compatibility to all example servers (needed by kotlin example host as Kotlin mcp sdk only supports sse)
• Create shared server-utils.ts module for HTTP transport setup
• Each example is still mostly self-contained (for stdio mode), and defers to single file helper for HTTP transports.

Changes

New: examples/shared/server-utils.ts

A shared utility for HTTP transports:

• /mcp (GET/POST/DELETE): Streamable HTTP with stateful sessions
• /sse + /messages: Legacy SSE for older clients

Features

• Stateful sessions: Proper session management with sessionIdGenerator
• Unified session store: Single Map for both transport types
• Error handling: Try/catch on all endpoints with JSON-RPC errors
• Graceful shutdown: Closes all sessions on SIGINT/SIGTERM
• Promise-based: startServer() returns Promise that resolves on listen, rejects on error
• Accessible: Binds to 0.0.0.0 for Android/device access

Server Pattern

Each server now uses explicit transport selection:

async function main() {
  if (process.argv.includes("--stdio")) {
    await server.connect(new StdioServerTransport());
  } else {
    const port = parseInt(process.env.PORT ?? "3001", 10);
    await startServer(server, { port, name: "Server Name" });
  }
}

main().catch((e) => {
  console.error(e);
  process.exit(1);
});

Servers Updated

All 9 TypeScript example servers:

• basic-server-react, basic-server-vanillajs
• budget-allocator-server, cohort-heatmap-server
• customer-segmentation-server, scenario-modeler-server
• system-monitor-server, threejs-server, wiki-explorer-server

Test plan

• npm run build passes
• npm test passes
• Manual verification of endpoints:
  • POST /mcp returns valid SSE initialize response
  • GET /sse returns SSE stream with endpoint event
  • POST /messages without session returns 404

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/modelcontextprotocol/ext-apps/@modelcontextprotocol/ext-apps@136

commit: 503d1c2

[jonathanhefner]

Do we need for the Kotlin SDK to connect to the basic examples? Or are the marketing examples sufficient?

Generally, I think we should keep basic-server-vanillajs and basic-server-react dead simple (and self-contained) as reference examples, so I would prefer that they only support a single transport.

[ochafik]

Do we need for the Kotlin SDK to connect to the basic examples? Or are the marketing examples sufficient?

@jonathanhefner I found bugs thanks to some of the examples already. If we adopt / keep the Kotlin & Swift examples it's good to be able to test them against something (native e2e tests will come in a while too), esp. since some users will only care about mobile apps hosts.

Generally, I think we should keep basic-server-vanillajs and basic-server-react dead simple (and self-contained) as reference examples, so I would prefer that they only support a single transport.

I kept the stdio part and their import inlined in each file, so users can trivially axe the http transports by removing two lines (or adopt it by bringing in that file, which imho should be in the TS MCP SDK in some form... but I digress).

We do need some kind of remote for our own testing though, and I didn't want this to cause too much duplication.

[jonathanhefner]

Ok, I don't want to block anything. I will take a look into alternatives at a later date. 👍