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-Idreplay - 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 requestsGET /mcp-- SSE streamDELETE /mcp-- close sessionGET /health-- health checkGET /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
