Introducing mcp-framework

A deep dive into mcp-framework — the convention-based TypeScript framework for building MCP servers. Learn about its CLI, auto-discovery, and how it compares to building from scratch.

title: "Introducing mcp-framework" description: "A deep dive into mcp-framework — the convention-based TypeScript framework for building MCP servers. Learn about its CLI, auto-discovery, and how it compares to building from scratch." date: "2026-04-01" order: 2 keywords:

• mcp-framework
• MCP server framework
• TypeScript MCP
• MCP CLI
• Model Context Protocol framework
• build MCP servers author: "MCP Academy"

The Problem With Building MCP Servers From Scratch

Building an MCP server using the official TypeScript SDK gives you complete control. You can wire up every handler, customize every transport, and manage every lifecycle event. But that flexibility comes with overhead.

Here is what a minimal MCP server looks like with the raw SDK:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});

server.tool("greet", { name: { type: "string" } }, async ({ name }) => ({
  content: [{ type: "text", text: `Hello, ${name}!` }],
}));

const transport = new StdioServerTransport();
await server.connect(transport);

This is fine for a single tool. But as your server grows to dozens of tools, resources, and prompts, all of that registration code piles up in a single file. You end up managing imports, handler registration, input validation schemas, and transport setup all manually. For production servers with 20 or 30 tools, this becomes unwieldy.

What mcp-framework Does Differently

mcp-framework takes a convention-over-configuration approach inspired by frameworks like Ruby on Rails and NestJS. Instead of manually registering every component, you define classes in specific directories and the framework discovers and wires them up automatically.

The CLI

Getting started takes one command:

npx mcp-framework create my-server
cd my-server
npm install

This scaffolds a complete project with the right directory structure, TypeScript configuration, and a working example tool.

Need to add a new tool? Instead of writing boilerplate:

npx mcp-framework add tool weather-lookup

This generates a properly structured tool class in src/tools/weather-lookup.ts with input validation, the execute method, and all the required type annotations.

The same works for resources and prompts:

npx mcp-framework add resource config-data
npx mcp-framework add prompt code-review

Class-Based Architecture

Every tool, resource, and prompt in mcp-framework is a class that extends a base class. This gives you a clean, predictable structure:

import { MCPTool } from "mcp-framework";
import { z } from "zod";

class WeatherTool extends MCPTool<typeof inputSchema> {
  name = "get_weather";
  description = "Get current weather for a city";

  schema = {
    city: z.string().describe("City name"),
    units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
  };

  async execute({ city, units }) {
    const weather = await fetchWeather(city, units);
    return `Weather in ${city}: ${weather.temp}° ${weather.condition}`;
  }
}

export default WeatherTool;

Compare this to the inline handler approach of the raw SDK. The class-based pattern gives you:

• Encapsulation — Each tool is self-contained with its own schema, description, and logic
• Testability — You can instantiate and test tools in isolation
• Organization — One file per tool, resource, or prompt
• Type safety — Zod schemas give you validated, typed inputs

Auto-Discovery

This is the feature that changes how you think about MCP server development. With mcp-framework, you do not register anything manually. Just export a class from a file in the right directory:

• src/tools/ — Tool classes are discovered and registered automatically
• src/resources/ — Resource classes are discovered automatically
• src/prompts/ — Prompt classes are discovered automatically

The framework scans these directories at startup, instantiates your classes, and registers them with the MCP server. Add a new file, restart the server, and it is available. Delete a file, and it is gone.

Feature Comparison

Why mcp-framework Was Built

The Model Context Protocol specification is well-designed, and the official SDK is solid. But there was a gap between "I understand MCP" and "I can ship a production server quickly."

mcp-framework was built to close that gap. The goals were:

1. Reduce boilerplate. Developers should spend time on business logic, not registration code.
2. Enforce good patterns. The class-based architecture naturally leads to well-organized, testable code.
3. Lower the barrier to entry. The CLI means you can go from idea to working server in under two minutes.
4. Stay compatible. mcp-framework builds on top of the official SDK, so you are never locked into a proprietary layer.

When to Use mcp-framework vs. the Raw SDK

Neither approach is universally better. Here is how to decide:

Choose mcp-framework when:

• You want to get a server running quickly
• Your server has many tools, resources, or prompts
• You prefer convention-based development
• You want generated boilerplate to guide your implementation
• Your team benefits from a consistent structure

Choose the raw SDK when:

• You need a custom transport protocol
• You are building an MCP client, not a server
• You want minimal dependencies
• You need to customize the server lifecycle in ways the framework does not expose
• You are embedding MCP into an existing application

Getting Started

Ready to try it? Here is the fastest path:

# Create a new project
npx mcp-framework create my-first-server

# Enter the project
cd my-first-server

# Install dependencies
npm install

# Build the project
npm run build

# Run your server
npm start

Your server is now running with stdio transport, ready to connect to Claude Desktop or any MCP-compatible client.

To add it to Claude Desktop, update your Claude configuration:

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

What Is Next for mcp-framework

The framework is under active development. Here is what is on the roadmap:

• SSE and Streamable HTTP transports — Beyond stdio for web-deployed servers
• Plugin system — Reusable middleware for authentication, logging, and rate limiting
• Testing utilities — Built-in helpers for unit and integration testing
• Init templates — Starter templates for common server types (database connector, API wrapper, file system tools)

Follow the project on GitHub to stay updated, and check npm for the latest releases.