example-mcp-stateful

learning-first boilerplate for stateful MCP servers over Streamable HTTP with TypeScript SDK v2.

part of a series: stdio · stateless · stateful (you are here) · sse

what it does

• runs a stateful MCP server where sessions persist across requests with in-memory storage
• implements the full Streamable HTTP lifecycle: POST /mcp (JSON-RPC), GET /mcp (SSE stream), DELETE /mcp (session close)
• demonstrates SSE resumability via an in-memory event store with Last-Event-Id replay
• registers example tools (add_note, list_notes, simulate_work), resources (session://overview, session://notes/{index}), and a prompt (study-notes)
• includes a scaffold CLI to generate new projects from templates
• vendors MCP TypeScript SDK v2 pre-release tarballs for reproducible installs

quick start

npm install
npm run dev

server starts at http://127.0.0.1:1453. endpoints:

• POST /mcp -- JSON-RPC requests
• GET /mcp -- SSE stream
• DELETE /mcp -- close session
• GET /health -- health check
• GET /sessions -- list active sessions

Docker alternative:

docker compose up --build -d

scaffold cli

generate a new project from the included templates:

npm run create -- init my-mcp-app

options: --force, --dir <path>, --sdk vendored|registry. see scaffold CLI docs for details.

documentation

sdk v2 context

this project targets MCP TypeScript SDK v2 pre-release (2.0.0-alpha.0). the v2 SDK splits the monolithic @modelcontextprotocol/sdk package into server, node, client, and core. this repo uses @modelcontextprotocol/server for McpServer and @modelcontextprotocol/node for NodeStreamableHTTPServerTransport. vendored tarballs under vendor/mcp-sdk-v2/ ensure reproducible installs until v2 reaches stable release.

license

MIT