MCP-Framework is a framework for building Model Context Protocol (MCP) servers elegantly in TypeScript.
MCP-Framework gives you architecture out of the box, with automatic directory-based discovery for tools, resources, and prompts. Use our powerful MCP abstractions to define tools, resources, or prompts in an elegant way. Our cli makes getting started with your own MCP server a breeze
- 🛠️ Automatic discovery and loading of tools, resources, and prompts
- Multiple transport support (stdio, SSE, HTTP Stream)
- TypeScript-first development with full type safety
- Built on the official MCP SDK
- Easy-to-use base classes for tools, prompts, and resources
- Out of the box authentication for SSE endpoints
The following projects and services are built using MCP Framework:
A crypto tipping service that enables AI assistants to help users send cryptocurrency tips to content creators directly from their chat interface. The MCP service allows for:
- Checking wallet types for users
- Preparing cryptocurrency tips for users/agents to complete Setup instructions for various clients (Cursor, Sage, Claude Desktop) are available in their MCP Server documentation.
# Install the framework globally
npm install -g mcp-framework
# Create a new MCP server project
mcp create my-mcp-server
# Navigate to your project
cd my-mcp-server
# Your server is ready to use!
The framework provides a powerful CLI for managing your MCP server projects:
# Create a new project
mcp create <your project name here>
# Create a new project with the new EXPERIMENTAL HTTP transport
Heads up: This will set cors allowed origin to "*", modify it in the index if you wish
mcp create <your project name here> --http --port 1337 --cors
# Add a new tool
mcp add tool price-fetcher
The framework provides comprehensive validation to ensure your tools are properly documented and functional:
# Build with automatic validation (recommended)
npm run build
# Build with custom validation settings
MCP_SKIP_TOOL_VALIDATION=false npm run build # Force validation (default)
MCP_SKIP_TOOL_VALIDATION=true npm run build # Skip validation (not recommended)
# Validate all tools have proper descriptions (for Zod schemas)
mcp validate
This command checks that all tools using Zod schemas have descriptions for every field. The validation runs automatically during build, but you can also run it standalone:
- âś… During build:
npm run build
automatically validates tools - âś… Standalone:
mcp validate
for manual validation - âś… Development: Use
defineSchema()
helper for immediate feedback - âś… Runtime: Server validates tools on startup
Example validation error:
❌ Tool validation failed:
❌ PriceFetcher.js: Missing descriptions for fields in price_fetcher: symbol, currency.
All fields must have descriptions when using Zod object schemas.
Use .describe() on each field, e.g., z.string().describe("Field description")
Integrating validation into CI/CD:
{
"scripts": {
"build": "tsc && mcp-build",
"test": "jest && mcp validate",
"prepack": "npm run build && mcp validate"
}
}
# Add a new prompt
mcp add prompt price-analysis
# Add a new prompt
mcp add resource market-data
-
Create your project:
mcp create my-mcp-server cd my-mcp-server
-
Add tools:
mcp add tool data-fetcher mcp add tool data-processor mcp add tool report-generator
-
Define your tool schemas with automatic validation:
// tools/DataFetcher.ts import { MCPTool, McpInput } from "mcp-framework"; import { z } from "zod"; const DataFetcherSchema = z.object({ // all fields should have .describe() url: z.string().url().describe("URL to fetch data from"), timeout: z.number().positive().default(5000).describe("Request timeout in milliseconds").optional() }); class DataFetcher extends MCPTool { name = "data_fetcher"; description = "Fetch data from external APIs"; schema = DataFetcherSchema; async execute(input: McpInput<this>) { // Fully typed input with autocomplete support const { url, timeout = 5000 } = input; // ... implementation } }
-
Build with automatic validation:
npm run build # Automatically validates schemas and compiles
-
Optional: Run standalone validation:
mcp validate # Check all tools independently
-
Test your server:
node dist/index.js # Server validates tools on startup
-
Add to MCP Client (see Claude Desktop example below)
Pro Tips:
- Use
defineSchema()
during development for immediate feedback - Build process automatically catches missing descriptions
- Server startup validates all tools before accepting connections
- Use TypeScript's autocomplete with
McpInput<this>
for better DX
Add this configuration to your Claude Desktop config file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"${projectName}": {
"command": "node",
"args":["/absolute/path/to/${projectName}/dist/index.js"]
}
}
}
Add this configuration to your Claude Desktop config file:
MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"${projectName}": {
"command": "npx",
"args": ["${projectName}"]
}
}
}
- Make changes to your tools
- Run
npm run build
to compile - The server will automatically load your tools on startup
The framework supports the following environment variables for configuration:
Variable | Description | Default |
---|---|---|
MCP_ENABLE_FILE_LOGGING | Enable logging to files (true/false) | false |
MCP_LOG_DIRECTORY | Directory where log files will be stored | logs |
MCP_DEBUG_CONSOLE | Display debug level messages in console (true/false) | false |
Example usage:
# Enable file logging
MCP_ENABLE_FILE_LOGGING=true node dist/index.js
# Specify a custom log directory
MCP_ENABLE_FILE_LOGGING=true MCP_LOG_DIRECTORY=my-logs node dist/index.js
# Enable debug messages in console
MCP_DEBUG_CONSOLE=true node dist/index.js
MCP Framework uses Zod schemas for defining tool inputs, providing type safety, validation, and automatic documentation:
import { MCPTool, McpInput } from "mcp-framework";
import { z } from "zod";
const AddToolSchema = z.object({
a: z.number().describe("First number to add"),
b: z.number().describe("Second number to add"),
});
class AddTool extends MCPTool {
name = "add";
description = "Add tool description";
schema = AddToolSchema;
async execute(input: McpInput<this>) {
const result = input.a + input.b;
return `Result: ${result}`;
}
}
export default AddTool;
Key Benefits:
- âś… Single source of truth - Define types and validation in one place
- âś… Automatic type inference - TypeScript types are inferred from your schema
- âś… Rich validation - Leverage Zod's powerful validation features
- âś… Required descriptions - Framework enforces documentation
- âś… Better IDE support - Full autocomplete and type checking
- âś… Cleaner code - No duplicate type definitions
The framework supports all Zod features:
import { MCPTool, McpInput } from "mcp-framework";
import { z } from "zod";
const AdvancedSchema = z.object({
// String constraints and formats
email: z.string().email().describe("User email address"),
name: z.string().min(2).max(50).describe("User name"),
website: z.string().url().optional().describe("Optional website URL"),
// Number constraints
age: z.number().int().positive().max(120).describe("User age"),
rating: z.number().min(1).max(5).describe("Rating from 1 to 5"),
// Arrays and objects
tags: z.array(z.string()).describe("List of tags"),
metadata: z.object({
priority: z.enum(['low', 'medium', 'high']).describe("Task priority"),
dueDate: z.string().optional().describe("Due date in ISO format")
}).describe("Additional metadata"),
// Default values
status: z.string().default('pending').describe("Current status"),
// Unions and enums
category: z.union([
z.literal('personal'),
z.literal('work'),
z.literal('other')
]).describe("Category type")
});
class AdvancedTool extends MCPTool {
name = "advanced_tool";
description = "Tool demonstrating advanced Zod features";
schema = AdvancedSchema;
async execute(input: McpInput<this>) {
// TypeScript automatically knows all the types!
const { email, name, website, age, rating, tags, metadata, status, category } = input;
console.log(input.name.toUpperCase()); // âś… TypeScript knows this is valid
console.log(input.age.toFixed(2)); // âś… Number methods available
console.log(input.tags.length); // âś… Array methods available
console.log(input.website?.includes("https")); // âś… Optional handling
return `Processed user: ${name}`;
}
}
The McpInput<this>
type automatically infers the correct input type from your schema, eliminating the need for manual type definitions:
class MyTool extends MCPTool {
schema = z.object({
name: z.string().describe("User name"),
age: z.number().optional().describe("User age"),
tags: z.array(z.string()).describe("User tags")
});
async execute(input: McpInput<this>) {
// TypeScript automatically knows:
// input.name is string
// input.age is number | undefined
// input.tags is string[]
console.log(input.name.toUpperCase()); // âś… TypeScript knows this is valid
console.log(input.age?.toFixed(2)); // âś… Handles optional correctly
console.log(input.tags.length); // âś… Array methods available
}
}
No more duplicate interfaces or generic type parameters needed!
All schema fields must have descriptions. This ensures your tools are well-documented and provides better user experience in MCP clients.
The framework validates descriptions at multiple levels:
npm run build # Automatically validates during compilation
Use the defineSchema
helper for immediate feedback:
import { defineSchema } from "mcp-framework";
// This will throw an error immediately if descriptions are missing
const MySchema = defineSchema({
name: z.string(), // ❌ Error: Missing description
age: z.number().describe("User age") // âś… Good
});
mcp validate # Check all tools for proper descriptions
The server automatically validates tools on startup.
To skip validation (not recommended):
# Skip during build
MCP_SKIP_TOOL_VALIDATION=true npm run build
# Skip during development
NODE_ENV=production npm run dev
import { MCPServer } from "mcp-framework";
const server = new MCPServer();
// OR (mutually exclusive!) with SSE transport
const server = new MCPServer({
transport: {
type: "sse",
options: {
port: 8080 // Optional (default: 8080)
}
}
});
// Start the server
await server.start();
The stdio transport is used by default if no transport configuration is provided:
const server = new MCPServer();
// or explicitly:
const server = new MCPServer({
transport: { type: "stdio" }
});
To use Server-Sent Events (SSE) transport:
const server = new MCPServer({
transport: {
type: "sse",
options: {
port: 8080, // Optional (default: 8080)
endpoint: "/sse", // Optional (default: "/sse")
messageEndpoint: "/messages", // Optional (default: "/messages")
cors: {
allowOrigin: "*", // Optional (default: "*")
allowMethods: "GET, POST, OPTIONS", // Optional (default: "GET, POST, OPTIONS")
allowHeaders: "Content-Type, Authorization, x-api-key", // Optional (default: "Content-Type, Authorization, x-api-key")
exposeHeaders: "Content-Type, Authorization, x-api-key", // Optional (default: "Content-Type, Authorization, x-api-key")
maxAge: "86400" // Optional (default: "86400")
}
}
}
});
To use HTTP Stream transport:
const server = new MCPServer({
transport: {
type: "http-stream",
options: {
port: 8080, // Optional (default: 8080)
endpoint: "/mcp", // Optional (default: "/mcp")
responseMode: "batch", // Optional (default: "batch"), can be "batch" or "stream"
batchTimeout: 30000, // Optional (default: 30000ms) - timeout for batch responses
maxMessageSize: "4mb", // Optional (default: "4mb") - maximum message size
// Session configuration
session: {
enabled: true, // Optional (default: true)
headerName: "Mcp-Session-Id", // Optional (default: "Mcp-Session-Id")
allowClientTermination: true, // Optional (default: true)
},
// Stream resumability (for missed messages)
resumability: {
enabled: false, // Optional (default: false)
historyDuration: 300000, // Optional (default: 300000ms = 5min) - how long to keep message history
},
// CORS configuration
cors: {
allowOrigin: "*" // Other CORS options use defaults
}
}
}
});
The HTTP Stream transport supports two response modes:
-
Batch Mode (Default): Responses are collected and sent as a single JSON-RPC response. This is suitable for typical request-response patterns and is more efficient for most use cases.
-
Stream Mode: All responses are sent over a persistent SSE connection opened for each request. This is ideal for long-running operations or when the server needs to send multiple messages in response to a single request.
You can configure the response mode based on your specific needs:
// For batch mode (default):
const server = new MCPServer({
transport: {
type: "http-stream",
options: {
responseMode: "batch"
}
}
});
// For stream mode:
const server = new MCPServer({
transport: {
type: "http-stream",
options: {
responseMode: "stream"
}
}
});
- Session Management: Automatic session tracking and management
- Stream Resumability: Optional support for resuming streams after connection loss
- Batch Processing: Support for JSON-RPC batch requests/responses
- Comprehensive Error Handling: Detailed error responses with JSON-RPC error codes
MCP Framework provides optional authentication for SSE endpoints. You can choose between JWT and API Key authentication, or implement your own custom authentication provider.
import { MCPServer, JWTAuthProvider } from "mcp-framework";
import { Algorithm } from "jsonwebtoken";
const server = new MCPServer({
transport: {
type: "sse",
options: {
auth: {
provider: new JWTAuthProvider({
secret: process.env.JWT_SECRET,
algorithms: ["HS256" as Algorithm], // Optional (default: ["HS256"])
headerName: "Authorization" // Optional (default: "Authorization")
}),
endpoints: {
sse: true, // Protect SSE endpoint (default: false)
messages: true // Protect message endpoint (default: true)
}
}
}
}
});
Clients must include a valid JWT token in the Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
import { MCPServer, APIKeyAuthProvider } from "mcp-framework";
const server = new MCPServer({
transport: {
type: "sse",
options: {
auth: {
provider: new APIKeyAuthProvider({
keys: [process.env.API_KEY],
headerName: "X-API-Key" // Optional (default: "X-API-Key")
})
}
}
}
});
Clients must include a valid API key in the X-API-Key header:
X-API-Key: your-api-key
You can implement your own authentication provider by implementing the AuthProvider
interface:
import { AuthProvider, AuthResult } from "mcp-framework";
import { IncomingMessage } from "node:http";
class CustomAuthProvider implements AuthProvider {
async authenticate(req: IncomingMessage): Promise<boolean | AuthResult> {
// Implement your custom authentication logic
return true;
}
getAuthError() {
return {
status: 401,
message: "Authentication failed"
};
}
}
MIT