MCP Server Starter
Production-shaped remote MCP server starter — Streamable HTTP on Cloudflare Workers, stateless + stateful patterns, typed tools, discovery, rate limiting, and Vitest tests.
File Structure 11 files
Documentation Preview README excerpt
MCP Server Starter — Remote Streamable HTTP on Cloudflare Workers
A production-shaped starter for building a **remote Model Context Protocol (MCP)
server** that any MCP client (Claude Desktop, Cursor, Cline, OpenCode, or your own
agent) can connect to over the network. It uses the Streamable HTTP transport
and runs on Cloudflare Workers (or any Web-standard runtime: Deno, Bun, Node 18+).
This is the exact shape used to ship a live, registry-listed commerce MCP server —
generalized, anonymized, and reduced to a clean starting point you can extend.
Why this exists
Most MCP tutorials show a local stdio server. Real agents increasingly connect
to remote servers over HTTP. Remote servers are harder: you have to handle the
Streamable HTTP transport correctly, decide between stateless and session modes,
run inside a serverless runtime with no Node built-ins, and expose a discovery
surface so clients can find you. This starter solves all of that.
Features
- Streamable HTTP transport — Web-standard
Request/Response, works on
Workers/Deno/Bun with no Node-only APIs.
- Stateless mode by default — a fresh server per request, no Durable Objects
required; ideal for read-heavy public tools. A documented path to stateful
sessions is included.
- Typed tools with zod schemas — two worked example tools (
echo,add) show
input validation, structured content, and error contracts.
- Friendly discovery — a plain
GET /mcpreturns a JSON descriptor instead of
an opaque 406, plus a /.well-known/mcp.json manifest.
- Rate limiting — a token-bucket limiter (in-memory, with a KV upgrade note).
- Tests — a Vitest suite that drives the server through the transport end to
end (initialize, tools/list, tools/call).
Requirements
- Node.js 18+ (for local dev and tests)
- A Cloudflare account (free tier is fine) for deployment
npm
Quick start
npm install
npm test # runs the Vitest suite against the in-process server
npm run dev # wrangler dev — serves /mcp locally
Point an MCP client at http://localhost:8787/mcp (Streamable HTTP). Or smoke-test
with curl:
curl http://localhost:8787/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json, text/event-stream' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
File tree
*... continues with setup instructions, usage examples, and more.*