MCP StateForge

Build, debug, and deploy stateless MCP servers against the 2026-07-28 specification.

npm create stateforge@latest my-server
cd my-server && npm run dev

Scaffolds a TypeScript + Express MCP server with a pluggable StateStore, a working multi-turn example built on explicit state handles, a visual inspector, and deploy configs for Vercel and Docker.

---

Why this exists

The 2026-07-28 revision removed protocol-level sessions. No initialize handshake, no Mcp-Session-Id, no held-open bidirectional stream. Every request is self-describing and can land on any instance behind a plain load balancer.

That is a large win for scaling and a real problem for anything multi-turn. The pattern that replaces sessions is the explicit state handle: a tool mints cart_7f3a9c2e5b1d, returns it, and every later tool takes it as an argument. The model can see the handle, hold several at once, and thread them between tools.

StateForge is that pattern, written out properly — with the storage abstraction, the handle validation, the multi-round-trip confirmation flow, and the debugging surface that a stateless server otherwise has no way to give you.

---

Repository layout

packages/create-stateforge/   The CLI. Zero runtime dependencies.
templates/default/            What gets scaffolded. A complete, working server.

templates/default is deliberately not a pnpm workspace member: it is copied verbatim into a user's project, so its dependencies must resolve on their own.

---

The CLI

create-stateforge [directory] [options]

  --name <name>          npm package name (default: the directory name)
  --store <memory|redis> State backend to configure (default: memory)
  --pm <npm|pnpm|yarn|bun>
                         Package manager to install with (default: detected)
  --no-install           Skip dependency installation
  --no-git               Skip `git init`
  -y, --yes              Accept every default, ask nothing

Interactive by default; falls back to defaults automatically when stdin is not a TTY, so it works unattended in CI.

It has no runtime dependencies. A create-* package is the first thing a user runs, and every dependency is install latency they pay before seeing anything.

---

What gets generated

A server whose whole point is that it holds nothing between requests:

• StateStore — get / set / update / delete / list / clear. In-memory implementation for local work (per-key locking, TTL, versioning); Redis implementation for production (Lua compare-and-swap, SCAN rather than KEYS). Swapping backends is one environment variable.
• Explicit handles — mintHandle('cart') produces cart_<12 hex>; assertHandle validates shape before the value is ever used as a store key.
• A shopping cart example — create_cart, add_item, set_item_quantity, remove_item, view_cart, abandon_cart, checkout. Every mutating tool requires the handle.
• Multi-round-trip checkout — returns input_required, the client answers and retries, HMAC-signed requestState carries the quoted total so a cart that moved mid-flow gets re-quoted instead of charged.
• The inspector — live tools/list, schema-generated call forms, and a state browser where records are editable JSON. Single HTML file, no build step.
• Deployment — api/mcp.ts (four lines, because handler.fetch is already web-standard), vercel.json, and a multi-stage Dockerfile that runs unprivileged with a healthcheck.
• Tests — domain, store, and end-to-end JSON-RPC through the real handler.

Full details in templates/default/README.md.

---

Developing StateForge

pnpm install                 # workspace packages
pnpm template:install        # the template's own dependencies
pnpm typecheck               # CLI + template
pnpm test                    # the template's test suite
pnpm --filter create-stateforge build

build compiles the CLI and copies templates/default into the package as template/, so the published tarball is self-contained.

To try the CLI against the working tree:

pnpm --filter create-stateforge dev -- /tmp/try-it --yes --no-install

Bumping the protocol revision

MCP_PROTOCOL_VERSION in packages/create-stateforge/src/scaffold.ts is the single source of truth. It is substituted into the template as {{mcpProtocolVersion}} wherever the revision appears. Bump it alongside the SDK dependencies in templates/default/package.json.

---

Reference

• The 2026-07-28 specification
• Release notes
• TypeScript SDK v2

MIT licensed.