MCP Production Demo (TypeScript)

A minimal but genuinely production-shaped MCP server: real API calls (live GitHub API), typed config validation, structured logging, consistent error handling, auth on the network transport, health checks, graceful shutdown, Docker packaging, and tests. This is what the toy stdio scripts were missing.

What's different from the toy version

Concern	Toy version	This version
Data	hardcoded fake dict	live GitHub REST API
Config	none	zod-validated env, fails fast on boot if misconfigured
Errors	uncaught = crash/hang	every handler wrapped, typed errors, client never sees a stack trace
Logging	none	structured JSON (pino), stderr-only so it can't corrupt stdio protocol
Timeouts	none	every outbound call has an AbortController timeout
Auth	none	bearer token required on the HTTP transport
Transport	stdio only	both stdio (local/desktop) and Streamable HTTP (deployed)
Deployment	none	multi-stage Dockerfile, non-root user, health check
Tests	none	error-handling contract covered with node:test

Project layout

src/
  config.ts          env validation (zod) — the only place process.env is read
  lib/
    logger.ts         pino logger, stderr-only
    errors.ts         typed error classes (Validation / Upstream / Timeout)
    http.ts           fetch wrapper: timeout + typed errors
    safeTool.ts        wraps every tool: catch, log, clean client-facing result
  tools/
    github.ts          real tools: get_repo, search_issues (live GitHub API)
  mcpServer.ts          registers all tools onto an McpServer instance
  stdioEntry.ts         entrypoint for local/desktop clients
  httpEntry.ts           entrypoint for a deployed, authenticated server
  safeTool.test.ts        tests for the error-handling contract

Setup

npm install
cp .env.example .env
# edit .env: add a GITHUB_TOKEN (unauthenticated GitHub calls are capped
# at 60/hour and will 403 fast — I hit this in testing), and if you'll
# run the HTTP transport, an MCP_AUTH_TOKEN (openssl rand -hex 32)

Run it — stdio (local/desktop)

npm run dev:stdio

This is what you'd point Claude Desktop / Claude Code at directly (see their MCP config docs) instead of writing your own client script.

Run it — HTTP (deployed)

MCP_TRANSPORT=http npm run dev:http
# in another terminal:
curl http://localhost:3000/health
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer $MCP_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

A request with no/wrong Authorization header gets a 401 before it ever reaches the MCP layer.

Tests

npm test

Covers the actual thing that matters in production: no matter what a tool handler throws, the client always gets back a well-formed { content, isError } — never a raw stack trace, never a hang.

Docker

docker build -t mcp-production-demo .
docker run -p 3000:3000 \
  -e MCP_AUTH_TOKEN=$(openssl rand -hex 32) \
  -e GITHUB_TOKEN=ghp_xxx \
  mcp-production-demo

Multi-stage build (compiled output only ships, no devDependencies), runs as a non-root user, has a HEALTHCHECK.

Production decisions worth understanding (not just copying)

• Logs go to stderr, always. stdout is reserved for the JSON-RPC protocol stream on the stdio transport. A single stray console.log would silently corrupt every message after it — this bit me in early testing of similar setups, which is why logger.ts calls it out explicitly.
• Fail fast on bad config. config.ts validates env vars at import time and calls process.exit(1) on failure, with the specific field that's wrong. A server that boots "successfully" into a broken state is worse than one that refuses to start.
• Never forward raw errors to the client. safeTool.ts logs full detail server-side (including stack traces for unexpected errors) but only ever returns a small set of clean, typed messages to the MCP client. I confirmed this live: an unauthenticated call to the GitHub API from this sandbox hit their real rate limit and returned a 403 with a detailed message — the client only saw "The upstream service returned an error (403). Please try again later," while the full GitHub response was in the server log.
• Stateless HTTP by default. Each /mcp request gets a fresh McpServer + StreamableHTTPServerTransport. No shared session state means it scales horizontally with zero coordination. If you need long-lived stateful sessions (e.g. server-initiated notifications between calls), you'd switch to the SDK's stateful mode with a sessionId -> transport map — more capable, more to get right.
• Every outbound call has a timeout. lib/http.ts uses AbortController so a hung upstream can't hang your tool call indefinitely and, transitively, whatever's waiting on it.
• Graceful shutdown matters for zero-downtime deploys. httpEntry.ts handles SIGTERM/SIGINT by stopping new connections and waiting for in-flight ones to finish, with a forced-exit timeout as a backstop. Without this, a rolling deploy on k8s/ECS kills in-flight requests mid-response.

Where this still isn't "enterprise production"

Being straight about the gaps rather than overselling it:

• Auth is a single shared bearer token. Fine for an internal tool; for anything multi-tenant you'd want the SDK's OAuth support instead.
• No rate limiting on the HTTP endpoint itself (only on the upstream GitHub calls) — add something like express-rate-limit before internet exposure.
• No metrics/tracing (Prometheus, OpenTelemetry) — logs alone aren't enough to debug latency issues at scale.
• No CI pipeline — npm test and docker build should run in GitHub Actions (or similar) on every PR, not just locally.