Features

Projects Built with MCP Framework

Support our work

Read the full docs here

Creating a repository with mcp-framework

Using the CLI (Recommended)

# Install the framework globallynpm install -g mcp-framework# Create a new MCP server projectmcp create my-mcp-server# Navigate to your projectcd my-mcp-server# Your server is ready to use!

CLI Usage

Project Creation

# Create a new projectmcp create<your project name here># Create a new project with the new EXPERIMENTAL HTTP transportHeads up: This willset cors allowed origin to"*", modify itin the indexif you wishmcp create<your project name here> --http --port 1337 --cors

Options:

--http: Use HTTP transport instead of default stdio

--port : Specify HTTP port (default: 8080)

--cors: Enable CORS with wildcard (*) access

Adding a Tool

# Add a new toolmcp add tool price-fetcher

Building and Validation

# Build with automatic validation (recommended)npm run build# Build with custom validation settingsMCP_SKIP_TOOL_VALIDATION=false npm run build# Force validation (default)MCP_SKIP_TOOL_VALIDATION=true npm run build# Skip validation (not recommended)

Validating Tools

# Validate all tools have proper descriptions (for Zod schemas)mcp validate

❌ Tool validation failed:  ❌ PriceFetcher.js: Missing descriptionsforfieldsin 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")

{"scripts": {"build":"tsc && mcp-build","test":"jest && mcp validate","prepack":"npm run build && mcp validate"  }}

Adding a Prompt

# Add a new promptmcp add prompt price-analysis

Adding a Resource

# Add a new promptmcp add resource market-data

Development Workflow

4. **Build with automatic validation:**```bashnpm run build  # Automatically validates schemas and compiles

Using with Claude Desktop

Local Development

{"mcpServers": {"${projectName}": {"command":"node","args":["/absolute/path/to/${projectName}/dist/index.js"]}}}

After Publishing

{"mcpServers": {"${projectName}": {"command":"npx","args": ["${projectName}"]}}}

Building and Testing

Environment Variables

# Enable file loggingMCP_ENABLE_FILE_LOGGING=true node dist/index.js# Specify a custom log directoryMCP_ENABLE_FILE_LOGGING=true MCP_LOG_DIRECTORY=my-logs node dist/index.js# Enable debug messages in consoleMCP_DEBUG_CONSOLE=true node dist/index.js

Quick Start

Defining Tools

import{MCPTool,McpInput}from"mcp-framework";import{z}from"zod";constAddToolSchema=z.object({a:z.number().describe("First number to add"),b:z.number().describe("Second number to add"),});classAddToolextendsMCPTool{name="add";description="Add tool description";schema=AddToolSchema;asyncexecute(input:McpInput<this>){constresult=input.a+input.b;return`Result:${result}`;}}exportdefaultAddTool;

Advanced Zod Schema Features

import{MCPTool,McpInput}from"mcp-framework";import{z}from"zod";constAdvancedSchema=z.object({// String constraints and formatsemail: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 constraintsage:z.number().int().positive().max(120).describe("User age"),rating:z.number().min(1).max(5).describe("Rating from 1 to 5"),// Arrays and objectstags: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 valuesstatus:z.string().default('pending').describe("Current status"),// Unions and enumscategory:z.union([z.literal('personal'),z.literal('work'),z.literal('other')]).describe("Category type")});classAdvancedToolextendsMCPTool{name="advanced_tool";description="Tool demonstrating advanced Zod features";schema=AdvancedSchema;asyncexecute(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 validconsole.log(input.age.toFixed(2));// ✅ Number methods availableconsole.log(input.tags.length);// ✅ Array methods availableconsole.log(input.website?.includes("https"));// ✅ Optional handlingreturn`Processed user:${name}`;}}

Automatic Type Inference

classMyToolextendsMCPTool{schema=z.object({name:z.string().describe("User name"),age:z.number().optional().describe("User age"),tags:z.array(z.string()).describe("User tags")});asyncexecute(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 validconsole.log(input.age?.toFixed(2));// ✅ Handles optional correctlyconsole.log(input.tags.length);// ✅ Array methods available}}

Schema Validation & Descriptions

1. Build-time Validation (Recommended)

npm run build# Automatically validates during compilation

2. Development-time Validation

import{defineSchema}from"mcp-framework";// This will throw an error immediately if descriptions are missingconstMySchema=defineSchema({name:z.string(),// ❌ Error: Missing descriptionage:z.number().describe("User age")// ✅ Good});

3. Standalone Validation

mcp validate# Check all tools for proper descriptions

4. Runtime Validation

# Skip during buildMCP_SKIP_TOOL_VALIDATION=true npm run build# Skip during developmentNODE_ENV=production npm run dev

Setting up the Server

import{MCPServer}from"mcp-framework";constserver=newMCPServer();// OR (mutually exclusive!) with SSE transportconstserver=newMCPServer({transport:{type:"sse",options:{port:8080// Optional (default: 8080)}}});// Start the serverawaitserver.start();

Transport Configuration

stdio Transport (Default)

constserver=newMCPServer();// or explicitly:constserver=newMCPServer({transport:{type:"stdio"}});

SSE Transport

constserver=newMCPServer({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")}}}});

HTTP Stream Transport

constserver=newMCPServer({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 responsesmaxMessageSize:"4mb",// Optional (default: "4mb") - maximum message size// Session configurationsession:{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 configurationcors:{allowOrigin:"*"// Other CORS options use defaults}}}});

Response Modes

// For batch mode (default):constserver=newMCPServer({transport:{type:"http-stream",options:{responseMode:"batch"}}});// For stream mode:constserver=newMCPServer({transport:{type:"http-stream",options:{responseMode:"stream"}}});

HTTP Stream Transport Features

Authentication

OAuth 2.1 Authentication

import{MCPServer,OAuthProvider}from"mcp-framework";constserver=newMCPServer({transport:{type:"sse",options:{auth:{provider:newOAuthProvider({// Your authorization server (e.g., Cognito)authorizationServer:"https://your-domain.auth.us-east-1.amazoncognito.com",// OAuth client credentialsclientId:process.env.OAUTH_CLIENT_ID,clientSecret:process.env.OAUTH_CLIENT_SECRET,// Optional for public clients// The canonical URI of this MCP serverresourceUri:"https://mcp.example.com",// Required scopesrequiredScopes:["openid","profile"],}),endpoints:{sse:false,// SSE endpoint is publicmessages:true,// Messages require authentication}},// Handle OAuth callbacksoauth:{onCallback:async({ accessToken, refreshToken})=>{console.log("User authorized successfully!");},onError:async(error)=>{console.error("Authorization failed:",error);}}}}});

JWT Authentication

import{MCPServer,JWTAuthProvider}from"mcp-framework";import{Algorithm}from"jsonwebtoken";constserver=newMCPServer({transport:{type:"sse",options:{auth:{provider:newJWTAuthProvider({secret:process.env.JWT_SECRET,algorithms:["HS256"asAlgorithm],// Optional (default: ["HS256"])headerName:"Authorization"// Optional (default: "Authorization")}),endpoints:{sse:true,// Protect SSE endpoint (default: false)messages:true// Protect message endpoint (default: true)}}}}});

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

API Key Authentication

import{MCPServer,APIKeyAuthProvider}from"mcp-framework";constserver=newMCPServer({transport:{type:"sse",options:{auth:{provider:newAPIKeyAuthProvider({keys:[process.env.API_KEY],headerName:"X-API-Key"// Optional (default: "X-API-Key")})}}}});

X-API-Key: your-api-key

OAuth 2.1 Authentication

JWT Validation (Recommended for Performance)

import{MCPServer,OAuthAuthProvider}from"mcp-framework";constserver=newMCPServer({transport:{type:"http-stream",options:{port:8080,auth:{provider:newOAuthAuthProvider({authorizationServers:[process.env.OAUTH_AUTHORIZATION_SERVER],resource:process.env.OAUTH_RESOURCE,validation:{type:'jwt',jwksUri:process.env.OAUTH_JWKS_URI,audience:process.env.OAUTH_AUDIENCE,issuer:process.env.OAUTH_ISSUER,algorithms:['RS256','ES256']// Optional (default: ['RS256', 'ES256'])}}),endpoints:{initialize:true,// Protect session initializationmessages:true// Protect MCP messages}}}}});

OAUTH_AUTHORIZATION_SERVER=https://auth.example.comOAUTH_RESOURCE=https://mcp.example.comOAUTH_JWKS_URI=https://auth.example.com/.well-known/jwks.jsonOAUTH_AUDIENCE=https://mcp.example.comOAUTH_ISSUER=https://auth.example.com

Token Introspection (Recommended for Centralized Control)

import{MCPServer,OAuthAuthProvider}from"mcp-framework";constserver=newMCPServer({transport:{type:"sse",options:{auth:{provider:newOAuthAuthProvider({authorizationServers:[process.env.OAUTH_AUTHORIZATION_SERVER],resource:process.env.OAUTH_RESOURCE,validation:{type:'introspection',audience:process.env.OAUTH_AUDIENCE,issuer:process.env.OAUTH_ISSUER,introspection:{endpoint:process.env.OAUTH_INTROSPECTION_ENDPOINT,clientId:process.env.OAUTH_CLIENT_ID,clientSecret:process.env.OAUTH_CLIENT_SECRET}}})}}}});

OAUTH_AUTHORIZATION_SERVER=https://auth.example.comOAUTH_RESOURCE=https://mcp.example.comOAUTH_AUDIENCE=https://mcp.example.comOAUTH_ISSUER=https://auth.example.comOAUTH_INTROSPECTION_ENDPOINT=https://auth.example.com/oauth/introspectOAUTH_CLIENT_ID=mcp-serverOAUTH_CLIENT_SECRET=your-client-secret

OAuth Features

Popular OAuth Providers

Client Usage

# Make a request with OAuth tokencurl -X POST http://localhost:8080/mcp \  -H"Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \  -H"Content-Type: application/json" \  -d'{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'# Discover OAuth configurationcurl http://localhost:8080/.well-known/oauth-protected-resource

Security Best Practices

Custom Authentication

import{AuthProvider,AuthResult}from"mcp-framework";import{IncomingMessage}from"node:http";classCustomAuthProviderimplementsAuthProvider{asyncauthenticate(req:IncomingMessage):Promise<boolean|AuthResult>{// Implement your custom authentication logicreturntrue;}getAuthError(){return{status:401,message:"Authentication failed"};}}

License