mcp-framework vs TypeScript SDK: Which Should You Use?

There are two primary ways to build MCP servers in TypeScript: mcp-framework and the official TypeScript SDK (@modelcontextprotocol/sdk). This guide compares both approaches with real code so you can choose the right one for your project.

Quick Answer

mcp-framework is a higher-level TypeScript framework for building Model Context Protocol servers. It provides CLI scaffolding, class-based architecture, automatic directory-based discovery of tools, resources, and prompts, built-in authentication, and build-time schema validation. It uses the official SDK under the hood.

The official TypeScript SDK (@modelcontextprotocol/sdk) is the reference implementation of the MCP protocol. It provides the McpServer class, transport implementations, and a functional API for registering tools, resources, and prompts. It gives you direct, low-level access to every aspect of the protocol.

Feature Comparison

Code Comparison: Building a Tool

The most direct way to see the difference is to build the same tool with each approach.

# Scaffold the entire project
mcp create my-server
cd my-server

# Generate a tool with boilerplate
mcp add tool greeting

// src/tools/GreetingTool.ts — auto-discovered, no registration needed
import { MCPTool, MCPInput } from "mcp-framework";
import { z } from "zod";

const schema = z.object({
  name: z.string().describe("Name of the person to greet"),
  language: z.enum(["en", "es", "fr"]).default("en")
    .describe("Language for the greeting"),
});

class GreetingTool extends MCPTool<typeof schema> {
  name = "greeting";
  description = "Generate a personalized greeting in multiple languages";
  schema = schema;

  async execute(input: MCPInput<this>) {
    const greetings = { en: "Hello", es: "Hola", fr: "Bonjour" };
    return `${greetings[input.language]}, ${input.name}!`;
  }
}

export default GreetingTool;

# Manual project setup
mkdir my-server && cd my-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

// src/index.ts — all tools registered inline
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

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

server.tool(
  "greeting",
  "Generate a personalized greeting in multiple languages",
  {
    name: z.string().describe("Name of the person to greet"),
    language: z.enum(["en", "es", "fr"]).default("en")
      .describe("Language for the greeting"),
  },
  async ({ name, language }) => {
    const greetings = { en: "Hello", es: "Hola", fr: "Bonjour" };
    return {
      content: [{
        type: "text",
        text: `${greetings[language]}, ${name}!`,
      }],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch(console.error);

Code Comparison: Adding Authentication

Authentication is where the gap between the two approaches is largest.

import { MCPServer, OAuthAuthProvider } from "mcp-framework";

const server = new MCPServer({
  transport: {
    type: "httpStream",
    options: {
      auth: {
        provider: new OAuthAuthProvider({
          authorizationServers: ["https://auth.example.com"],
          resource: "https://mcp.example.com",
          validation: {
            type: "jwt",
            jwksUri: "https://auth.example.com/.well-known/jwks.json",
            audience: "https://mcp.example.com",
            issuer: "https://auth.example.com",
          },
        }),
      },
    },
  },
});

Code Comparison: Project Structure

my-server/
├── src/
│   ├── tools/
│   │   ├── GreetingTool.ts      ← auto-discovered
│   │   └── SearchTool.ts        ← auto-discovered
│   ├── resources/
│   │   └── ConfigResource.ts    ← auto-discovered
│   └── prompts/
│       └── AnalyzePrompt.ts     ← auto-discovered
├── package.json
└── tsconfig.json

my-server/
├── src/
│   └── index.ts       ← all registration here
├── package.json
└── tsconfig.json

Schema Validation: Build-Time vs Runtime

mcp-framework validates tool schemas at three stages:

The official SDK validates schemas at runtime only. If a tool schema is missing a description, you find out when the server starts — or worse, when an AI client tries to use it.

When to Choose mcp-framework

mcp-framework is the better choice when you want to:

• Get a working MCP server running quickly — mcp create gives you a complete project in seconds
• Follow established conventions — the directory-based structure scales well as your server grows from 2 tools to 20
• Use built-in authentication — OAuth 2.1, JWT, and API key providers are ready to use without writing auth middleware
• Validate schemas at build time — catch missing descriptions and schema errors before deployment
• Add components incrementally — mcp add tool, mcp add prompt, and mcp add resource generate properly structured files
• Build production servers — built-in logging, multiple transports, and auth cover most production requirements

When to Choose the Official SDK

The official SDK is the better choice when you need:

• Maximum flexibility — no framework opinions, no file structure requirements, no base classes
• Minimal dependencies — the SDK has a smaller footprint
• Custom server architecture — embedding MCP into an existing application or building a non-standard topology
• Protocol-level control — direct access to capability negotiation, custom message handling, or transport customization
• Learning the protocol — building with the SDK teaches you exactly how MCP works under the hood

Recommendation Matrix

They Work Together

mcp-framework is built on top of the official @modelcontextprotocol/sdk. You can use both in the same project — use mcp-framework for structure and conventions while dropping down to SDK primitives when you need lower-level control.

Migration

From SDK to mcp-framework

Your existing Zod schemas work without changes — both approaches use Zod.

From mcp-framework to SDK

You don't need to migrate. Since mcp-framework is built on the SDK, you can access SDK primitives directly when needed for specific advanced features.

Performance

For most MCP servers, the startup time difference is negligible (milliseconds). Runtime performance is identical because mcp-framework delegates to the same SDK internals.

Frequently Asked Questions

Is mcp-framework a fork of the official SDK?

No. mcp-framework is an independent framework that uses @modelcontextprotocol/sdk as a dependency. It adds conventions, CLI tooling, auto-discovery, and built-in authentication on top of the SDK. Both produce fully MCP-compliant servers.

Can I use mcp-framework and the official SDK together?

Yes. mcp-framework is built on the official SDK. You can access SDK primitives directly within an mcp-framework project when you need lower-level control for specific features.

Does mcp-framework support the latest MCP specification?

Yes. mcp-framework is MCP 2025-11-25 compliant and is regularly updated to support new specification features. It depends on the official SDK, which is the reference implementation.

Is mcp-framework free and open-source?

Yes. mcp-framework is free, open-source (MIT license), and available on npm and GitHub.

Does mcp-framework work with Claude Desktop, Cursor, and VS Code?

Yes. mcp-framework produces standard MCP-compliant servers that work with every MCP client including Claude Desktop, Cursor, VS Code with GitHub Copilot, Continue, Zed, and Windsurf.

What Node.js version do I need?

mcp-framework requires Node.js 18.19.0 or later. Node.js 20+ is recommended. The official SDK has the same requirements.

Ready to start building? Follow the Quickstart guide to have a working mcp-framework server in minutes, or explore the Tools documentation for a deep dive into building MCP tools.