example-mcp-stateful

yigitkonur/example-mcp-stateful

3.3

If you are the rightful owner of example-mcp-stateful and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This repository provides a reference implementation of a stateful MCP calculator server using the Streamable HTTP transport.

Tools
5
Resources
0
Prompts
0

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 for details.

documentation

docdescription
install, run, verify endpoints
module layout, session lifecycle, resumability
generate new projects from templates
v2 packages, vendoring, migration
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