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

doc	description
getting started	install, run, verify endpoints
architecture	module layout, session lifecycle, resumability
scaffold cli	generate new projects from templates
sdk v2 notes	v2 packages, vendoring, migration
validation	smoke tests, primitive checks, release checklist

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