MCP Server Boilerplate

Production-ready Model Context Protocol server boilerplate with TypeScript, authentication, and multiple transports.

Features

Interactive CLI — npx mcp-server-boilerplate init to scaffold a new project in seconds
Two transports — stdio (local) and Streamable HTTP (remote)
Authentication — API key, JWT, and OAuth 2.1 with pluggable providers
TOML configuration — human-readable config.toml with env var overrides
5 example tools — calculator, echo, fetch-api, file-ops, in-memory database
3 example resources — server config, dynamic key-value store, user directory
2 example prompts — code review, summarization
Full test suite — Vitest with in-memory MCP client/server
Docker ready — multi-stage Dockerfile + docker-compose
CI/CD — GitHub Actions with lint, test, build, and npm publish

Tech Stack

Node.js 24 LTS / TypeScript 6
@modelcontextprotocol/sdk v1.29+
Express 5 / Zod / pino / jose / smol-toml

Quick Start

Create a new project (recommended)

npx mcp-server-boilerplate init my-server

The interactive CLI will ask you to pick:

Transport mode (stdio, HTTP, or both)
Authentication (none, API key, or OAuth 2.1)
Whether to include example tools/resources/prompts
Whether to install dependencies

Or clone the boilerplate directly

git clone https://github.com/jeandbonicel/mcp-server-boilerplate.git
cd mcp-server-boilerplate
npm install

# Run in development (stdio)
npm run dev:stdio

# Run in development (HTTP)
npm run dev:http

# Build for production
npm run build

# Run tests
npm test

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/mcp-server-boilerplate/dist/transports/stdio.js"]
    }
  }
}

Usage as Remote Server

# Start with no auth (development)
npm run start:http

# Start with API key auth
MCP_AUTH_MODE=api-key MCP_API_KEYS=my-secret-key npm run start:http

# Start with OAuth 2.1 (demo provider)
MCP_AUTH_MODE=oauth npm run start:http

Then connect from any MCP client to http://localhost:3000/mcp.

Configuration

Configuration uses TOML (config.toml) with environment variable overrides. Edit config.toml directly for most settings. Env vars take precedence when set.

config.toml

[server]
name = "mcp-server"
version = "1.0.0"

[http]
port = 3000
host = "127.0.0.1"

[logging]
level = "info"  # fatal | error | warn | info | debug | trace

[auth]
mode = "none"   # "none" | "api-key" | "oauth"
# keys = ["my-secret-key-1", "my-secret-key-2"]

# [auth.jwt]
# issuer = "https://auth.example.com"
# audience = "mcp-server"
# secret = "your-shared-secret"
# jwks_uri = "https://auth.example.com/.well-known/jwks.json"

# [auth.oauth]
# issuer_url = "https://auth.example.com"

Environment Variable Overrides

Env vars override TOML values when set. Useful for Docker, CI, or secrets.

| Variable | TOML key | Default | Description | |---|---|---|---| | MCP_SERVER_NAME | server.name | mcp-server | Server name | | MCP_SERVER_VERSION | server.version | 1.0.0 | Server version | | MCP_HTTP_PORT | http.port | 3000 | HTTP port | | MCP_HTTP_HOST | http.host | 127.0.0.1 | HTTP bind host | | LOG_LEVEL | logging.level | info | Log level | | MCP_AUTH_MODE | auth.mode | none | Auth mode | | MCP_API_KEYS | auth.keys | — | Comma-separated API keys | | MCP_JWT_ISSUER | auth.jwt.issuer | — | JWT issuer | | MCP_JWT_AUDIENCE | auth.jwt.audience | — | JWT audience | | MCP_JWT_SECRET | auth.jwt.secret | — | JWT shared secret | | MCP_JWKS_URI | auth.jwt.jwks_uri | — | JWKS endpoint URL | | MCP_OAUTH_ISSUER_URL | auth.oauth.issuer_url | — | OAuth server URL | | MCP_CONFIG_PATH | — | ./config.toml | Custom path to TOML config |

Authentication

No Auth (default)

Best for local development with stdio transport. No configuration needed.

API Key

Static bearer tokens. In config.toml: ``toml [auth] mode = "api-key" keys = ["my-secret-key-1", "my-secret-key-2"] ` Or via env: MCP_AUTH_MODE=api-key MCP_API_KEYS=key1,key2. Clients send Authorization: Bearer key1` with every request.

OAuth 2.1

Full OAuth flow with browser-based login. Set auth.mode = "oauth" in config.toml or MCP_AUTH_MODE=oauth. The boilerplate includes a demo in-memory OAuth provider that auto-approves all requests.

For production, replace DemoOAuthProvider in src/auth/oauth-provider.ts with your real identity provider, or use JwtVerifier to validate tokens from an external OAuth server (Auth0, Keycloak, etc.):

// In src/transports/http.ts, replace the oauth block:
const verifier = new JwtVerifier({
  jwksUri: "https://your-auth-server.com/.well-known/jwks.json",
  issuer: "https://your-auth-server.com",
  audience: "your-mcp-server",
});
authMiddleware = requireBearerAuth({ verifier });

Adding Custom Auth

Create a new file in src/auth/ implementing OAuthTokenVerifier:

   import type { OAuthTokenVerifier } from "@modelcontextprotocol/sdk/server/auth/provider.js";
   import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";

   export class MyVerifier implements OAuthTokenVerifier {
     async verifyAccessToken(token: string): Promise<AuthInfo> {
       // Your verification logic here
       return { token, clientId: "...", scopes: ["..."] };
     }
   }

Add your auth mode to the config enum in src/config.ts
Wire it in src/transports/http.ts

Adding Your Own Tools

Each tool is a module that exports a register(server) function:

// src/tools/my-tool.ts
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export function register(server: McpServer): void {
  server.registerTool("my-tool", {
    title: "My Tool",
    description: "Does something useful",
    inputSchema: {
      input: z.string().describe("The input"),
    },
  }, async ({ input }) => ({
    content: [{ type: "text", text: `Result: ${input}` }],
  }));
}

Then register it in src/tools/index.ts:

import * as myTool from "./my-tool.js";

export function registerAll(server: McpServer): void {
  // ...existing tools...
  myTool.register(server);
}

Project Structure

config.toml                — TOML configuration (human-readable)
src/
  cli.ts                 — Interactive project scaffolder
  config.ts              — TOML + env loader, Zod-validated
  logger.ts              — pino structured logging
  server.ts              — McpServer factory + registration
  transports/
    stdio.ts             — CLI entry point (bin)
    http.ts              — Express + Streamable HTTP + auth
  auth/
    api-key-verifier.ts  — Bearer token verification
    jwt-verifier.ts      — JWT/JWKS verification
    oauth-provider.ts    — Demo OAuth 2.1 server
  tools/                 — Example tools (echo, calculator, etc.)
  resources/             — Example resources (config, items, users)
  prompts/               — Example prompts (code-review, summarize)
tests/                   — Vitest test suite

Docker

# Build and run
docker compose up --build

# Or manually
docker build -t mcp-server .
docker run -p 3000:3000 --env-file .env mcp-server

Scripts

| Script | Description | |---|---| | npm run dev:stdio | Development with stdio (tsx) | | npm run dev:http | Development with HTTP (tsx) | | npm run build | Compile TypeScript | | npm run start:stdio | Production stdio | | npm run start:http | Production HTTP | | npm test | Run tests | | npm run lint | Lint with ESLint | | npm run format | Format with Prettier | | npm run typecheck | Type check without emitting |

MCP Server Boilerplate