mcp-framework
About
A TypeScript framework for building Model Context Protocol (MCP) servers.
Explore
- 🛠️ 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 (OAuth 2.1, JWT, API Key)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
mcp-frameworkCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
npm install -g mcp-framework
The framework provides a powerful CLI for managing your MCP server projects:
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:
MCP Framework provides optional authentication for SSE endpoints. You can choose between JWT, API Key, OAuth 2.1 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
MCP Framework supports OAuth 2.1 authentication per the MCP specification (2025-06-18), including Protected Resource Metadata (RFC 9728) and proper token validation with JWKS support.
OAuth authentication works with both SSE and HTTP Stream transports and supports two validation strategies:
Clients must include a valid OAuth access token in the Authorization header:
curl http://localhost:8080/.well-known/oauth-protected-resource
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"
};
}
}
cp .env.example .env
import { DocsServer, FumadocsRemoteSource } from "@mcpframework/docs";
const source = new FumadocsRemoteSource({
baseUrl: "https://docs.myapi.com",
});
const server = new DocsServer({
source,
name: "my-api-docs",
version: "1.0.0",
});
server.start();
claude mcp add my-api-docs -e DOCS_BASE_URL=https://docs.myapi.com -- node /path/to/my-api-docs/dist/index.js
```
For Claude Desktop / Cursor configuration and full documentation, see the @mcpframework/docs README.
search_docs
Search documentation by keyword or phrase
get_page
Retrieve full markdown content of a page
list_sections
Browse the documentation tree structure
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"
}
}
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
| Tool | Description |
|------|-------------|
| search_docs | Search documentation by keyword or phrase |get_page
| | Retrieve full markdown content of a page |list_sections` | Browse the documentation tree structure |
|
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"mcp-framework": {
"mcp-framework": {
"command": "node",
"args": [
"dist/index.js",
"#",
"Server",
"validates",
"tools",
"on",
"startup"
]
}
}
}
}McpServers
{
"mcp-framework": {
"command": "node",
"args": [
"dist/index.js",
"#",
"Server",
"validates",
"tools",
"on",
"startup"
]
}
}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
Features
- 🛠️ 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 (OAuth 2.1, JWT, API Key)
Projects Built with MCP Framework
The following projects and services are built using MCP Framework:
- ### tip.md
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.
Support our work
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
