# mcp-production-notes

Companion code for **[Shipping a production MCP server on the 2026-07-28 spec: auth, rate limits, and observability](https://isokron.ai/notes/production-mcp-server)**.

A small notes server built on the v2 TypeScript SDK that shows the three things that change most once MCP sessions go away: who is calling, how much they may do, and how you find out what happened.

| File | What it shows |
|---|---|
| `src/server.ts` | Tool definitions, per-tool scopes (`requireScopes`), `cacheHints` for cacheable results |
| `src/http.ts` | Streamable HTTP app: bearer auth, protected-resource metadata, Host/Origin allow-lists |
| `src/verifier.ts` | Token introspection, audience check, scope mapping |
| `src/limits.ts` | Per-subject rate limits that return `isError` results, not transport errors |
| `src/observe.ts` | OpenTelemetry spans following the MCP semantic conventions |
| `src/stdio.ts` | The local, no-auth path (`serveStdio`) for single-user servers |
| `src/main.ts` | Wiring it together behind a TLS-terminating proxy |
| `test/smoke.ts` | Drives the listings through a real Node HTTP server and the v2 client |

## Run it

```bash
npm ci
npm run typecheck   # strict TypeScript
npm run smoke       # 17 end-to-end checks
```

Requires Node 22+. Targets `@modelcontextprotocol/server` 2.4, `@modelcontextprotocol/node` 2.1, zod 4.

The smoke test stubs the introspection endpoint; everything else (HTTP, auth headers, scopes, rate limits, error shapes) runs for real. `mcp.example.com` and `auth.example.com` in `src/main.ts` are placeholders.

## Disclosure

The article and this code were drafted with AI assistance (Claude) and reviewed, run and tested by the author. The smoke test is the source of truth for every behavior the article marks "verified".

## Related

- [kronicle-lite](https://github.com/rafe-walker/kronicle-lite) — local-first MCP document store with hash-chained history (the "one bearer token" case the article starts from)
- [mcp-catalog-snap](https://github.com/rafe-walker/mcp-catalog-snap) — fail CI when an MCP server's tool catalog drifts

## License

Apache-2.0