Skip to main content
Glama
rafe-walker

mcp-production-notes

by rafe-walker
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

mcp-production-notes

Companion code for Shipping a production MCP server on the 2026-07-28 spec: auth, rate limits, and observability.

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

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.

Related MCP server: mcp-note-app

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 — local-first MCP document store with hash-chained history (the "one bearer token" case the article starts from)

  • mcp-catalog-snap — fail CI when an MCP server's tool catalog drifts

License

Apache-2.0

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • mcp-note-app

    PyaePhyo-Win
    F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for a full-stack note-taking application, exposing CRUD tools for notes with SSE transport for AI agent integration.
    1
    -

  • Permissioned MCP Server

    sn0bored
    A
    license
    A
    quality
    D
    maintenance
    A compact MCP server demonstrating explicit tool boundaries, least-privilege discovery, execution-time authorization, destructive-action confirmation, and metadata-only audit logs using a local note store.
    3
    MIT

  • Snackbar MCP Server

    johnawadlow
    A
    license
    Not graded
    quality
    C
    maintenance
    A personal note store exposed as an MCP server. Enables any MCP-speaking assistant to create, search, list, and categorize notes, with per-client bearer tokens for author attribution.
    533 npm
    MIT