MCP Server Template

A production-ready template for building Model Context Protocol (MCP) servers with TypeScript.

Features

• MCP SDK 1.24.3 - Latest SDK with 2025-11-25 spec support
• Dual Transport - Stdio (Claude Desktop) and HTTP (cloud deployment)
• OAuth 2.1 Foundations - Protected resource metadata, bearer token structure
• SQLite Caching - TTL-based caching with sql.js (WebAssembly)
• Observability - Sentry error tracking + OpenTelemetry tracing
• Security - PII sanitization, rate limiting, DNS rebinding protection
• Type Safety - Strict TypeScript with Zod validation

Quick Start

# Clone and install
git clone <this-repo> my-mcp-server
cd my-mcp-server
npm install

# Development mode (hot reload)
npm run dev

# Build and run
npm run build
npm start

# Test with MCP Inspector
npm run inspector

Project Structure

src/
├── index.ts              # CLI entry point
├── server.ts             # MCP server implementation
├── instrumentation.ts    # Sentry + OpenTelemetry setup
├── config/
│   └── index.ts          # Environment configuration
├── db/
│   ├── database.ts       # SQLite connection (sql.js)
│   └── cache.ts          # TTL-based caching
├── tools/
│   ├── registry.ts       # Tool registration pattern
│   └── examples.ts       # Example tool implementations
├── transport/
│   └── http-transport.ts # HTTP with OAuth foundations
├── shared/
│   ├── logger.ts         # Structured logging
│   ├── errors.ts         # Custom error classes
│   ├── rate-limiter.ts   # Per-source rate limiting
│   ├── pii-sanitizer.ts  # PII detection/removal
│   └── tracing.ts        # OpenTelemetry utilities
└── types/
    └── index.ts          # TypeScript type definitions

Configuration

Environment variables (prefix with MCP_SERVER_):

Variable	Default	Description
MCP_SERVER_NAME	mcp-server-template	Server name
MCP_SERVER_VERSION	0.1.0	Server version
MCP_SERVER_LOG_LEVEL	info	Log level: debug, info, warning, error
MCP_SERVER_DB_PATH	.data/cache.db	SQLite database path
MCP_SERVER_CACHE_ENABLED	true	Enable/disable caching
MCP_SERVER_CACHE_TTL	3600	Default cache TTL (seconds)
MCP_SERVER_TIMEOUT	30000	Request timeout (ms)
MCP_SERVER_TRANSPORT	stdio	Transport: stdio or http
MCP_SERVER_PORT	3000	HTTP port (when transport=http)
MCP_SERVER_HOST	127.0.0.1	HTTP host (when transport=http)
MCP_SERVER_SENTRY_DSN	-	Sentry DSN for error tracking
OTEL_ENABLED	false	Enable OpenTelemetry tracing
OTEL_EXPORTER_OTLP_ENDPOINT	-	OTLP collector endpoint
MCP_SERVER_DEBUG	false	Debug mode (skips auth)

Creating Tools

Tools are registered with the ToolRegistry using Zod schemas:

import { z } from 'zod';
import { getToolRegistry } from './tools/registry.js';

// Define input schema
const MyToolInputSchema = z.object({
  query: z.string().min(1).describe('Search query'),
  limit: z.number().positive().optional().default(10),
});

type MyToolInput = z.infer<typeof MyToolInputSchema>;

// Implement handler
async function myToolHandler(input: MyToolInput) {
  // Your implementation here
  return {
    success: true,
    data: { results: [] },
  };
}

// Register tool
const registry = getToolRegistry();
registry.register(
  'my_tool',
  'Description of what this tool does',
  MyToolInputSchema,
  myToolHandler
);

Transport Modes

Stdio (Default)

For Claude Desktop and local integrations:

npm start

Add to Claude Desktop config:

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

HTTP

For cloud deployment:

MCP_SERVER_TRANSPORT=http npm start

Endpoints:

• GET /health - Health check
• GET /.well-known/mcp - MCP server metadata
• GET /.well-known/oauth-protected-resource - OAuth metadata (RFC 9728)
• GET /mcp - SSE stream for server events
• POST /mcp - JSON-RPC requests
• DELETE /mcp - Close session

Security Features

PII Sanitization

Automatically detects and masks sensitive data:

import { sanitizePii } from './shared/pii-sanitizer.js';

const safe = sanitizePii('Contact: user@example.com');
// Output: "Contact: [EMAIL]"

Rate Limiting

Per-source rate limiting with exponential backoff:

import { getRateLimiter } from './shared/rate-limiter.js';

const limiter = getRateLimiter();
limiter.configure('external-api', {
  requestsPerWindow: 100,
  windowMs: 60000,
});

await limiter.waitForSlot('external-api');
// Make request...

DNS Rebinding Protection

HTTP transport validates Host headers against allowlist.

Observability

Sentry

Error tracking with PII filtering:

MCP_SERVER_SENTRY_DSN=https://xxx@sentry.io/xxx npm start

OpenTelemetry

Distributed tracing:

OTEL_ENABLED=true \
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
npm start

Use tracing utilities:

import { withSpan, createApiSpan } from './shared/tracing.js';

const result = await withSpan('my-operation', async (span) => {
  span.setAttribute('custom.attr', 'value');
  return doWork();
});

Development

# Type check
npm run check

# Lint
npm run lint
npm run lint:fix

# Format
npm run format

# Test
npm test
npm run test:coverage

# Validate (all checks)
npm run validate

MCP 2025-11-25 Spec Compliance

Feature	Status
Tools	✅ Implemented
Resources	📝 Scaffolded
Prompts	📝 Scaffolded
Streamable HTTP	✅ Implemented
.well-known/mcp	✅ Implemented
OAuth 2.1 Foundations	✅ Scaffolded
Tasks	❌ Not yet
Elicitation	❌ Not yet

OAuth 2.1 Implementation

The template includes foundations for OAuth 2.1 per the MCP spec:

1. Protected Resource Metadata (RFC 9728) at /.well-known/oauth-protected-resource
2. Bearer token middleware structure (implement JWT validation)
3. WWW-Authenticate headers with resource_metadata reference
4. Scope checking structure for tool authorization

To complete OAuth integration:

1. Choose an authorization server (Auth0, Logto, etc.)
2. Implement JWT validation in bearerAuthMiddleware
3. Add JWKS fetching and caching
4. Configure scopes per tool

See MCP Authorization Spec for details.

License

MIT

References

• MCP Specification
• MCP SDK
• MCP TypeScript SDK