mcp-server-starter-kit

A production-shaped starter for building a Model Context Protocol server in TypeScript.

Most MCP tutorials stop at "hello world" over stdio. The hard parts — the ones that actually break servers in the wild — start right after: authentication, transport choice, request timeouts, SSRF guards, and a deploy that survives cold starts. This kit ships those, small enough to read in one sitting.

The MCP protocol is the easy part. Everything around it is where servers die. This kit is that "everything around it," kept minimal and honest.

• stdio + streamable HTTP, switched by one env var.
• Bearer auth that fails closed — no token configured means every HTTP request is rejected, with a real 401 + WWW-Authenticate, constant-time comparison, and the token never logged.
• Legible errors — a typed ToolError becomes a proper MCP error result (isError: true), so an agent sees [forbidden_host] ... instead of a silent hang or an opaque internal error.
• A real example tool (http_get_json) with the guards every fetch tool needs and most omit: input validation, https-only, an SSRF host allowlist, and a hard timeout.
• Stateless HTTP by design — the shape that survives serverless cold starts (see DEPLOYMENT.md).
• Tests + typecheck out of the box (a drop-in GitHub Actions CI is in DEPLOYMENT.md).

---

Quickstart (stdio, ~60 seconds)

git clone https://github.com/park11innyc-lgtm/mcp-server-starter-kit
cd mcp-server-starter-kit
npm install
cp .env.example .env
npm run dev          # starts on stdio; logs "ready on stdio" to stderr

Point Claude Desktop / Cursor at it — claude_desktop_config.json:

{
  "mcpServers": {
    "starter-kit": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/mcp-server-starter-kit/src/index.ts"]
    }
  }
}

Restart the client and you'll have two tools: ping and http_get_json.

Run it remotely (streamable HTTP + auth)

# generate a token
node -e "console.log(require('crypto').randomBytes(24).toString('base64url'))"

# put it in .env  ->  MCP_BEARER_TOKENS=<that token>
npm run serve:http   # POST http://localhost:3000/mcp   (GET /healthz is open)

Every request to /mcp now needs Authorization: Bearer <token>. With no token set, the server refuses everything — that "fail closed" default is the point.

---

The two example tools

Tool	What it shows
ping	The minimum viable tool: zero input, structured JSON out. Use it as your liveness check.
http_get_json	The patterns a real outbound tool needs — zod input validation, an https-only rule, an SSRF allowlist (ALLOWED_FETCH_HOSTS), and an AbortController timeout — with every failure mapped to a typed error.

Add your own in src/tools.ts and register it in src/server.ts. The try/catch → toToolResult wrapper there is what keeps your failures legible; keep using it.

The parts tutorials skip (and where they live)

• Auth that fails closed → src/auth.ts. Bearer tokens are the correct first step; full delegated OAuth 2.1 is a deliberate non-goal of a starter — DEPLOYMENT.md points at where to add it.
• stdout is sacred on stdio → src/index.ts. One stray console.log corrupts the JSON-RPC stream. Log to stderr only.
• Cold starts → src/http.ts is stateless on purpose. DEPLOYMENT.md explains why and when to add sessions.
• SSRF → an MCP tool that fetches URLs is an open proxy into your network unless you allowlist hosts. http_get_json does.

Layout

src/
  index.ts    entry — picks stdio vs http
  server.ts   builds the McpServer, registers tools, wraps handlers
  tools.ts    the example tools (add yours here)
  auth.ts     bearer auth for the HTTP transport (fail closed)
  http.ts     stateless streamable-HTTP server
  errors.ts   ToolError + toToolResult
test/
  tools.test.ts

Scripts

npm run dev         # stdio, hot
npm run serve:http  # http transport
npm run build       # tsc -> dist/
npm start           # run built server
npm test            # vitest
npm run typecheck   # tsc --noEmit

License

MIT — do whatever you want with it. Attribution appreciated, not required.

---

_{Built as an honest reference, not a paywall. A production companion focused on ops automation (retry/dedup, cost caps, runbooks) is in the works — a link will land here when it ships.}