MCP Server Framework

A production-ready TypeScript framework for building Model Context Protocol servers — born out of the belief that MCP server development shouldn't mean reinventing infrastructure every time.

Why This Framework?

When I started building an MCP server for Komodo MCP Server, I quickly realized that the MCP SDK gives you protocol handling, but everything around it — transport management, session lifecycle, security middleware, configuration, observability, error handling — you're on your own. Every MCP server project ends up solving the same problems from scratch if you want a flexible,production-ready MCP server.

This framework extracts that infrastructure into a reusable foundation. The goal is simple: you focus on your API, tools, resources and prompts — the framework handles everything else.

It's opinionated where it matters (security defaults, structured logging, transport abstraction) and flexible where it should be (pluggable session stores, optional OpenTelemetry, multiple transport modes). Whether you're building a local CLI tool for Claude Desktop or a multi-client HTTP service in Docker — the same defineTool() call works everywhere.

Disclaimer

This framework is a personal project built with best effort and care. AI tools (GitHub Copilot, Claude) were used during development — for code generation, architecture exploration, and documentation. All AI-generated code and documentation has been critically reviewed, tested, and refined by me.

That said: this software is provided as-is, without warranty of any kind. See the license for the full legal terms. If you find bugs or have ideas, issues and contributions are always welcome.

License

LGPL-3.0 — GNU Lesser General Public License v3.0 or later

Features

🔌 Transport & Protocol

• Multi-Transport — Stdio, Streamable HTTP (stateful & stateless), SSE (legacy). Same defineTool() code works everywhere.
• HTTPS / TLS — Native TLS support with configurable cert/key paths, passphrase, and trust proxy for reverse proxies.
• Stateless Mode — Per-request sessions for serverless and edge deployments, zero state overhead.
• SSE Resumability — Pluggable EventStore interface for resilient SSE stream reconnections.

🔐 Authentication & Security

• OAuth 2.1 / OIDC — Opt-in auth with three patterns: OIDC auto-discovery (Keycloak, Auth0, Okta, Azure AD), upstream OAuth proxy (GitHub, Google), and custom token verification.
• Scope-Based Access Control — Permission guards (requireAuth, requireScope, hasScope) for fine-grained tool access.
• Security Middleware Stack — Helmet headers, DNS rebinding protection, configurable rate limiting, protocol version validation — all enabled by default for HTTP transports.
• Secret Scrubbing — JWT, Bearer tokens, and API keys automatically redacted from logs. CWE-117 log injection guard strips ANSI escapes and neutralizes injection attempts.

🛠️ Developer Experience

• Type-Safe Factories — defineTool(), defineResource(), defineResourceTemplate(), definePrompt() with full Zod schema validation and auto-completion.
• MCP Apps — defineApp() combines a tool with a UI resource in one declaration, enabling rich client interfaces via _meta.ui.resourceUri.
• MCP Tasks (experimental) — defineTask() for async background work with tasks/list, tasks/get, tasks/cancel protocol support.
• Zero-Boilerplate — Auto-registration via global registries. Import a tool file = it's registered. createServer() picks it up automatically.
• Response Helpers — text(), json(), error(), image(), audio(), multi() — no manual content array assembly.
• Builder Pattern — McpServerBuilder fluent API for full control: custom providers, lifecycle hooks, explicit wiring.

📊 Observability & Operations

• OpenTelemetry — Distributed tracing and metrics with zero-cost lazy loading (no overhead when disabled). OTLP and Prometheus export.
• Structured Logging — Pipeline-based logger with JSON (ECS) and text formatters, file + console writers, AsyncLocalStorage for automatic request context.
• Dual Logging — Framework logs go to stderr/files; MCP client notifications go to the connected client via SDK — simultaneously.
• Health Endpoints — Kubernetes-ready /health (liveness) and /ready (readiness with API connectivity, session capacity, and configuration checks).

⚙️ Configuration & Session Management

• 12-Factor Config — Five-level cascade: defaults → .env → config file (TOML/YAML/JSON) → environment variables → programmatic overrides.
• Pluggable Session Store — SessionStore interface with in-memory default. Bring your own Redis, PostgreSQL, or any backend.
• Session Lifecycle — Configurable idle timeouts, heartbeat keep-alive, dead connection cleanup, and max session capacity.
• Connection State Manager — Generic ConnectionStateManager<TApi> with health checks, state transitions, and reconnection tracking for API clients.
• Graceful Shutdown — SIGINT/SIGTERM handling, session drain, configurable shutdown timeouts.

🧩 Error System

• Typed Error Hierarchy — AppError base with categories: MCP, Session, Transport, Validation, Configuration, Operation, System.
• FrameworkErrorFactory — Single import for all error types with unique IDs, HTTP/JSON-RPC code mappings, recovery hints, and cause chains.

Quick Start

import { createServer, defineTool, text, z } from 'mcp-server-framework';

defineTool({
  name: 'greet',
  description: 'Greet someone',
  input: z.object({ name: z.string() }),
  handler: async ({ input }) => text(`Hello, ${input.name}!`),
});

const { start } = createServer({
  name: 'my-server',
  version: '1.0.0',
});

await start();

That's it. The tool is auto-registered, the server starts on stdio by default.

Installation

npm install mcp-server-framework @modelcontextprotocol/sdk zod

For HTTP transport (Express is a peer dependency, optional for stdio-only):

npm install express

For OpenTelemetry (all optional):

npm install @opentelemetry/api @opentelemetry/sdk-node @opentelemetry/sdk-metrics \
  @opentelemetry/instrumentation-http @opentelemetry/instrumentation-express \
  @opentelemetry/exporter-trace-otlp-http @opentelemetry/exporter-prometheus

Requirements: Node.js ≥20.0.0, TypeScript ≥5.0

Primary API

High-Level: createServer() + define*()

import { createServer, defineTool, defineResource, definePrompt, text, json, z } from 'mcp-server-framework';

// Tools — auto-registered in the global registry
defineTool({
  name: 'health',
  description: 'Check server health',
  input: z.object({}),
  handler: async () => text('OK'),
});

// Resources — static URI-based content
defineResource({
  uri: 'config://version',
  name: 'Version Info',
  handler: async () => json({ version: '1.0.0' }),
});

// Prompts — reusable prompt templates
definePrompt({
  name: 'summarize',
  description: 'Summarize a topic',
  args: [{ name: 'topic', description: 'Topic to summarize', required: true }],
  handler: async ({ args }) => ({
    messages: [{ role: 'user', content: { type: 'text', text: `Summarize: ${args.topic}` } }],
  }),
});

// Start the server
const { start } = createServer({
  name: 'my-server',
  version: '1.0.0',
});
await start();

Advanced: McpServerBuilder

For full control over server composition:

import { McpServerBuilder } from 'mcp-server-framework';

const server = new McpServerBuilder()
  .withOptions({
    name: 'advanced-server',
    version: '1.0.0',
    transport: { mode: 'http', host: '0.0.0.0', port: 8000 },
  })
  .withToolProvider(myToolRegistry)
  .withResourceProvider(myResourceProvider)
  .withLifecycleHooks({
    onStarted: () => console.log('Server ready'),
  })
  .build();

await server.start();

Definition Helpers

Function	Description	Auto-Registration
defineTool()	MCP Tool with Zod schema and handler	globalToolRegistry
defineResource()	Static MCP Resource (URI-based)	globalResourceRegistry
defineResourceTemplate()	URI-template Resource with parameters	globalResourceRegistry
definePrompt()	MCP Prompt with optional arguments	globalPromptRegistry
defineApp()	MCP App (Tool + Resource composition)	globalToolRegistry + globalResourceRegistry
defineTask()	Async background task tool (experimental)	globalTaskToolRegistry

Response Helpers

Function	Description
text()	Text content response
json()	JSON-serialized response
error()	Error response with isError: true
image()	Base64-encoded image
audio()	Base64-encoded audio
multi()	Multi-content response

Transport Modes

Transport	Protocol	Session Mode	Use Case
Stdio	—	Single session	CLI, local development (Claude Desktop, VS Code)
Streamable HTTP (stateful)	2025-03-26	Persistent sessions	Production, Docker, multi-client
Streamable HTTP (stateless)	2025-03-26	Per-request	Serverless, edge, horizontal scaling
SSE (legacy)	2024-11-05	Persistent sessions	Backwards compatibility

// Stdio (default)
createServer({ transport: { mode: 'stdio' } });

// HTTP
createServer({ transport: { mode: 'http', host: '0.0.0.0', port: 8000 } });

// HTTPS
createServer({ transport: { mode: 'https', host: '0.0.0.0', port: 8443 } });

// Stateless (serverless / edge)
createServer({ transport: { mode: 'http', host: '0.0.0.0', port: 8000, stateless: true } });

Configuration

The framework follows the 12-Factor App methodology. Sources are merged in order of precedence:

Defaults → .env file → Config file → Environment variables → Programmatic overrides

Variable	Default	Description
MCP_TRANSPORT	http	Transport mode: stdio, http, https
MCP_BIND_HOST	127.0.0.1	Host to bind to
MCP_PORT	8000	Port to listen on
MCP_STATELESS	false	Stateless mode (no sessions)
MCP_JSON_RESPONSE	false	Prefer JSON over SSE for non-streaming responses
MCP_BODY_SIZE_LIMIT	1mb	Max request body size
LOG_LEVEL	info	Log level: trace, debug, info, warn, error
OTEL_ENABLED	false	Enable OpenTelemetry tracing & metrics

Config file (auto-discovered as mcp-server.toml, .yaml, .json in CWD):

[transport]
mode = "http"
host = "0.0.0.0"
port = 8000

[security]
trust_proxy = "loopback"

[session]
timeout_ms = 1800000

[logging]
level = "info"
format = "json"

Subpath Exports

For advanced use cases, internal modules are available via subpath imports:

Import Path	Purpose
mcp-server-framework	Main API: createServer, defineTool, auth providers, guards, helpers
mcp-server-framework/logger	Logger configuration, child loggers
mcp-server-framework/connection	ConnectionStateManager for API clients
mcp-server-framework/session	Session internals, SessionStore interface
mcp-server-framework/telemetry	OpenTelemetry tracing & metrics
mcp-server-framework/errors	Error classes & FrameworkErrorFactory
mcp-server-framework/http	Express app, HTTP/HTTPS server (lazy-loaded)
mcp-server-framework/config	Config cache, env schema, Zod helpers

import { ConnectionStateManager } from 'mcp-server-framework/connection';
import { FrameworkErrorFactory } from 'mcp-server-framework/errors';
import { withSpan } from 'mcp-server-framework/telemetry';
import type { SessionStore } from 'mcp-server-framework/session';

Architecture

src/
├── mcp/           # MCP Protocol Layer
│   ├── capabilities/  # Registries, define*() factories, apps, tasks
│   ├── handlers/      # Ping, progress
│   ├── responses/     # text(), json(), error(), image(), audio(), multi()
│   └── types/         # ToolDefinition, ResourceDefinition, ToolContext
├── server/        # Server Infrastructure
│   ├── auth/          # OAuth 2.1, OIDC auto-discovery, guards
│   ├── builder/       # McpServerBuilder (fluent API)
│   ├── http/          # Express app factory, HTTP/HTTPS server (lazy-loaded)
│   ├── middleware/     # Helmet, DNS rebinding, rate limiting, auth
│   ├── routes/        # Health, readiness, metrics, streamable HTTP, SSE
│   ├── session/       # SessionManager, SessionStore, Housekeeper, auth context
│   ├── transport/     # Stdio, Streamable HTTP, SSE transports
│   └── telemetry/     # OpenTelemetry traces, metrics, SDK init (lazy-loaded)
├── api/           # API Client Abstraction
│   └── connection/    # ConnectionStateManager<TApi>
├── logger/        # Structured Logging
│   ├── scrubbing/     # Secret scrubbing, injection guard
│   ├── formatters/    # JSON (ECS), text
│   └── writers/       # Console, file, composite
├── errors/        # Error System
│   ├── core/          # AppError, ErrorCodes, HTTP/JSON-RPC mappings
│   └── categories/    # Validation, Connection, MCP, Operation, System
├── config/        # Configuration
│   └──                # Env schema (Zod), config cache, file parser
└── utils/         # Helpers

Security

The HTTP middleware stack runs before the MCP SDK processes any request:

Request → Trust Proxy → Helmet → DNS Rebinding → Rate Limiter → Auth → Protocol Version → SDK

• Helmet: Security headers (CSP, X-Frame-Options, HSTS, Referrer-Policy, etc.)
• DNS Rebinding Protection: Host header validation against allowed hosts
• Rate Limiting: Configurable window, max requests, and custom key generators
• Trust Proxy: Native Express trust-proxy support for reverse proxies (nginx, Traefik, Cloud LBs)
• Secret Scrubbing: JWT, Bearer tokens, API keys automatically redacted from all log output
• Log Injection Guard: CWE-117 protection — ANSI escapes stripped, injection attempts neutralized

Authentication

OAuth 2.1 and OIDC authentication is opt-in — servers work without auth by default.

import { createServer, createOidcProvider } from 'mcp-server-framework';

// OIDC auto-discovery (Keycloak, Auth0, Okta, Azure AD, ...)
const { provider, callbackHandler } = await createOidcProvider({
  issuer: 'https://auth.example.com',
  clientId: process.env.OIDC_CLIENT_ID!,
  clientSecret: process.env.OIDC_CLIENT_SECRET!,
  serverUrl: 'http://localhost:8000',
});

const { start } = createServer({
  name: 'secure-server',
  version: '1.0.0',
  transport: { mode: 'http' },
  auth: { provider, callbackHandler },
});
await start();

Supported patterns:

• OIDC Auto-Discovery — createOidcProvider() fetches .well-known/openid-configuration automatically
• Upstream OAuth Proxy — createUpstreamOAuthProvider() for GitHub, Google, and other OAuth services
• Custom Token Verifier — Implement TokenVerifier for API keys, custom JWTs, or any auth scheme
• Permission Guards — requireAuth(), requireScope(), hasScope() for tool-level access control

Health (/health) and metrics (/metrics) endpoints remain unauthenticated for liveness/readiness probes.

Error Handling

All framework errors extend AppError with structured metadata:

import { FrameworkErrorFactory } from 'mcp-server-framework/errors';

throw FrameworkErrorFactory.mcp.invalidRequest('Missing required parameter');
throw FrameworkErrorFactory.session.expired('sess-abc123');
throw FrameworkErrorFactory.validation.fieldRequired('name');

Each error includes: unique errorId (UUID), code, statusCode (HTTP), mcpCode (JSON-RPC), recoveryHint, cause chain, and timestamp.

Process Error Handling

The framework handles graceful shutdown (SIGINT, SIGTERM) but delegates process-level error handling to consumers. Add these handlers in your server entry point:

process.on('unhandledRejection', (reason) => {
  logger.error('Unhandled rejection: %s', reason);
});

process.on('uncaughtException', (error) => {
  logger.error('Uncaught exception: %s', error.message);
  process.exit(1);
});

Tech Stack

Core

Technology	Version	Purpose
TypeScript	^5.0	Strict mode, ES2022 target, exactOptionalPropertyTypes, verbatimModuleSyntax
Node.js	≥20.0.0	Runtime (ESM, node: built-ins)
@modelcontextprotocol/sdk	^1.27.1	MCP Protocol SDK — tools, resources, prompts, transports
Express	^5.2.1	HTTP/HTTPS transport (lazy-loaded, see DD-018)
Zod	^3.25.0	Runtime schema validation for tool inputs and config

Security & Middleware

Technology	Version	Purpose
Helmet	^8.1.0	Security headers (CSP, X-Frame-Options, HSTS, etc.)
express-rate-limit	^8.2.1	Configurable request rate limiting
CORS	^2.8.5	Cross-origin resource sharing

Observability (opt-in, lazy-loaded)

Technology	Version	Purpose
@opentelemetry/sdk-node	^0.213.0	OTEL SDK orchestration
@opentelemetry/api	^1.9.0	Tracing API, span context
@opentelemetry/sdk-metrics	^2.6.0	Metrics collection & export
@opentelemetry/instrumentation-http	^0.213.0	Automatic HTTP span instrumentation
@opentelemetry/instrumentation-express	^0.61.0	Automatic Express route instrumentation
@opentelemetry/exporter-prometheus	^0.213.0	Prometheus /metrics endpoint
@opentelemetry/exporter-trace-otlp-http	^0.213.0	OTLP trace export (Jaeger, Grafana, etc.)

Configuration & Utilities

Technology	Version	Purpose
dotenv	^17.3.1	.env file loading
smol-toml	^1.3.1	TOML config file parsing
yaml	^2.7.1	YAML config file parsing

Note: Express, Zod, and all OpenTelemetry packages are peer dependencies. OTEL packages are optional — install only what you need. Express is optional, stdio-only servers.