example-mcp-stateless

yigitkonur/example-mcp-stateless

3.2

If you are the rightful owner of example-mcp-stateless 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 an MCP calculator server using Streamable HTTP transport in a truly stateless mode.

Tools
4
Resources
0
Prompts
0

example-mcp-stateless

learning-first MCP boilerplate for HTTP stateless servers using TypeScript SDK v2 pre-release.

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

what it does

  • runs a stateless MCP server where every request gets a fresh McpServer instance -- no sessions, no state, no coordination
  • registers example tools (calculate, describe_stateless_limits), resources (boilerplate://limitations, boilerplate://topic/{topic}), and a prompt (design-next-tool)
  • includes a scaffold CLI to bootstrap new projects and generate tool/resource/prompt stubs
  • vendors SDK v2 pre-release tarballs for reproducible builds
  • ships with Docker support, CI workflow, and a smoke test

quick start

git clone https://github.com/yigitkonur/example-mcp-stateless.git
cd example-mcp-stateless
npm install
npm run dev

the server starts at http://127.0.0.1:1071/mcp. verify with:

curl http://127.0.0.1:1071/health

Docker alternative:

docker-compose up -d

scaffold cli

build the CLI first, then scaffold a new project:

npm run build
npm run cli -- init my-mcp-server --install

generate stubs inside an existing project:

npm run create -- generate tool my_tool
npm run create -- generate resource my_resource
npm run create -- generate prompt my_prompt

full reference:

documentation

documentdescription
install, run, configure, verify
module layout, stateless pattern, endpoint contract
init and generate command reference
v2 packages, vendoring, migration from v1
CI breakdown, smoke test, mcp-cli verification

sdk v2 context

this repo tracks MCP TypeScript SDK v2 in pre-release form. it uses the split package model (@modelcontextprotocol/server, @modelcontextprotocol/node, @modelcontextprotocol/express) and the registerTool/registerResource/registerPrompt APIs with Zod v4 schemas. tarballs are vendored in vendor/mcp-sdk-v2/ for reproducibility.

license

MIT