What you end up with
- An MCP server on your own URL, with your own tools, that Claude Code, Cursor, VS Code and other MCP clients can call.
- Auth you switch with one variable: none for local work, API keys for you and your team, or OAuth with per-tool scopes for public servers and claude.ai connectors.
- One codebase for Cloudflare Workers, Vercel, plain Node, Docker, a Raspberry Pi, or a local stdio process.
- A test suite that runs offline, and a smoke test you can point at any running server.
The live demo is this kit, unchanged, running on Cloudflare Workers.
Requirements
- Node.js 20 or newer on your computer.
- An MCP client to use it from, such as Claude Code, Cursor or VS Code.
- To deploy: a Cloudflare or Vercel account (both have free plans), or any host that runs Node or Docker.
- For OAuth only: an identity provider that issues JWTs, for example Auth0, Clerk, WorkOS, Stytch or Keycloak.
Try the free version first
mcp-server-starter-lite is the free, stdio-only part of this kit, on GitHub under the MIT license. It has two tools (current-time and convert-units), 7 tests and the same code style, and runs in Claude Code, Claude Desktop, Cursor and VS Code on your own machine.
This kit adds what you need once the server runs somewhere else: the stateless HTTP server, auth, deploy configs, storage, the other example tools and the eight guides.
The first five minutes
After you unzip the kit:
npm install
cp .env.example .env # then set API_KEYS to a long random string
npm test # 27 tests, offline
npm run dev # http://localhost:3000/mcp
In a second terminal, check it end to end, then connect a client:
npm run smoke -- http://localhost:3000/mcp YOUR_KEY
claude mcp add --transport http my-server http://localhost:3000/mcp \
--header "Authorization: Bearer YOUR_KEY"
Adding your own tool is one file in src/tools/ and one line in src/tools/index.ts. Guide 1 walks through it, and AGENTS.md tells Claude Code or Cursor how to do it the same way.
What is in the zip
mcp-server-starter/
README.md overview, quick start, deploy
AGENTS.md rules for AI coding assistants working in the repo
CHANGELOG.md LICENSE.md
docs/ the eight guides
src/
server.ts app.ts MCP server and the web-standard HTTP handler
config.ts validated settings; refuses placeholder keys in production
auth/ API keys, OAuth (JWT via JWKS), per-tool scopes
tools/ the seven example tools
resources/ prompts/ a resource, a resource template and a prompt
store/ in-memory, Workers KV and Upstash Redis note stores
entry/ node.ts, stdio.ts, worker.ts
api/mcp.ts Vercel function
test/ auth, HTTP and tool tests
scripts/smoke.ts checks any running server end to end
wrangler.jsonc vercel.json Dockerfile
.env.example .dev.vars.example
The eight guides
- Add your first tool. The five-minute version, calling an external API, per-user data and scopes, errors, letting your AI assistant do it, and testing it.
- Authentication: API keys and OAuth. API keys, OAuth with your identity provider, scopes per tool, and Origin and Host checks.
- Deploy to Vercel.
- Deploy to Cloudflare Workers. Including Workers KV for persistent storage.
- Deploy anywhere else. Plain Node (a VPS, a Raspberry Pi, a spare laptop), Docker, private-network-only setups, Deno, Bun, and stdio for desktop clients.
- Connect clients. Claude Code, Cursor, VS Code, Claude Desktop, claude.ai and other web connectors, OpenClaw, your own code and the MCP Inspector.
- Testing. How the offline tests work, writing a test, auth tests, and testing a deployed server.
- Production checklist. Auth and access, tools, treating tool input as untrusted, and operations.
The example tools
Each one teaches one pattern you will reuse. Delete the ones you do not need.
| Tool | Pattern |
|---|---|
create-note list-notes get-note delete-note | Per-user data with a swappable store, scoped to the verified caller |
get-weather | Calling an external API with timeouts and readable errors |
convert-units | Pure structured output with an output schema |
whoami | Reading the caller's identity and scopes |
Scripts
| Command | What it does |
|---|---|
npm run dev | Local HTTP server on port 3000 with reload |
npm run stdio | Run as a stdio server for desktop clients |
npm test | Run the test suite |
npm run typecheck | TypeScript check |
npm run smoke -- <url> [key] | Check a running or deployed server |
npm run cf:dev | Run on the local Workers runtime |
npm run cf:deploy | Deploy to Cloudflare Workers |
npm run inspect | Open the MCP Inspector |
Changelog
1.1.0
- Cloudflare Workers deployment, with Workers KV for notes.
- New guide: Deploy to Cloudflare Workers.
- 27 tests.
1.0.0
- First release: MCP TypeScript SDK v2 and the 2026-07-28 spec, three auth modes, Vercel, Node, Docker and stdio.
Every 1.x update is free for existing buyers.