MCP Server Boilerplate

A production-grade starting point for building Model Context Protocol (MCP) servers in native TypeScript. Clean enough for a weekend project, hardened enough for an enterprise deployment.

• ⚡️ Native TypeScript, strict, ESM (NodeNext)

• 🔌 Two transports out of the box — stdio (local clients) and Streamable HTTP (remote/hosted) with session management

• 🧱 Modular structure — one file per tool / resource / prompt, aggregated automatically

• ✅ Zod-validated tool I/O and environment config

• 🪵 Structured logging (pino) to stderr only, so stdio JSON-RPC stays clean

• 🛡️ DNS-rebinding protection (Host-header validation) + CORS + optional bearer auth

• 🧪 Vitest with fast in-memory client↔server tests

• 🧹 ESLint (type-checked) + Prettier + Husky pre-commit hooks

• 🐳 Multi-stage Dockerfile for the HTTP transport

• 🤖 Claude Code tooling — CLAUDE.md, skills, and slash commands baked in

Requirements

• Node.js >= 22.13 (required by pnpm 11)

• pnpm >= 11 (corepack enable will provide it)

Related MCP server: MCP Server Starter

Quick start

pnpm install
cp .env.example .env

# Local (stdio) development with hot reload
pnpm dev

# Remote (Streamable HTTP) development with hot reload
pnpm dev:http

Then build and run the compiled server:

pnpm build
pnpm start        # stdio
pnpm start:http   # Streamable HTTP on http://127.0.0.1:3000/mcp

Transports

The transport is chosen by the --transport CLI flag (which overrides the MCP_TRANSPORT env var), defaulting to stdio:

• stdio — the client spawns the server and speaks JSON-RPC over stdin/stdout. Use this for Claude Desktop, IDEs, and other local integrations.

• Streamable HTTP — an Express server at POST/GET/DELETE /mcp with per-session transports and a GET /healthz liveness endpoint. Use this for remote/hosted deployments.

Connect from Claude Desktop (stdio)

{
  "mcpServers": {
    "mcp-boilerplate": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
    },
  },
}

Authentication (HTTP)

The HTTP transport is unauthenticated by default (protected by ALLOWED_HOSTS). To require a bearer token, set AUTH_ENABLED=true and provide AUTH_TOKENS:

AUTH_ENABLED=true AUTH_TOKENS=my-secret-token pnpm start:http
# Requests to /mcp without "Authorization: Bearer my-secret-token" get 401.

The bundled verifier in src/core/auth.ts checks a static token allowlist — replace verifyAccessToken with real JWT verification or OAuth token introspection for production. The validated AuthInfo is available to tool handlers via extra.authInfo.

Configuration

All configuration is environment-based and validated at startup (see .env.example):

Project structure

src/
  index.ts          Entrypoint: transport resolution + graceful shutdown
  server.ts         createServer(): builds McpServer, registers everything
  config/env.ts     Zod-validated environment configuration
  core/             logger (stderr), errors (AppError + toToolError), pkg (name/version)
  transports/       stdio.ts, http.ts (Express + Streamable HTTP)
  tools/            echo.tool.ts + index.ts aggregator
  resources/        system-info.resource.ts + index.ts aggregator
  prompts/          summarize.prompt.ts + index.ts aggregator
tests/              Vitest, in-memory client↔server (helpers/connect.ts)

Adding features

Adding a feature is always: new file + one import line in the folder's index.ts.

# With Claude Code:
/new-tool weather "get the forecast for a city"
/new-resource changelog "expose CHANGELOG.md"
/new-prompt review "ask the model to review a diff"

Or by hand — copy src/tools/echo.tool.ts, define Zod schemas, register it in src/tools/index.ts, and add a test. See CLAUDE.md for the full conventions.

Testing & inspecting

pnpm test            # run once
pnpm test:watch      # watch mode
pnpm test:coverage   # coverage report
pnpm inspector       # launch the MCP Inspector against the server over stdio

Docker (HTTP transport)

docker build -t mcp-boilerplate .
docker run --rm -p 3000:3000 \
  -e ALLOWED_HOSTS=localhost,127.0.0.1 \
  mcp-boilerplate

# or with Docker Compose (includes a healthcheck):
docker compose up --build

Commits & releases

• Conventional Commits are enforced by a commit-msg hook (commitlint). Use feat:, fix:, chore:, docs:, etc. — e.g. feat(tools): add weather tool.

• Versioning uses changesets: pnpm changeset to record a change, pnpm changeset:version to bump + update the changelog, pnpm changeset:release to publish.

Claude Code tooling

This repo ships agent tooling under .claude/ and CLAUDE.md:

• karpathy-guidelines skill — behavioral guardrails (think first, stay simple, surgical changes, verify) vendored from multica-ai/andrej-karpathy-skills.

• mcp-add-tool / mcp-add-resource / mcp-add-prompt skills — encode this repo's exact patterns so new features stay consistent.

• /new-tool / /new-resource / /new-prompt slash commands.

• settings.json — a permission allowlist for the common project commands.

Scripts

License

MIT