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

Compare mcp-framework and the official TypeScript SDK for building MCP servers. See real code examples, feature differences, and a clear guide for choosing the right approach.

title: "mcp-framework vs TypeScript SDK: Which Should You Use?" description: "Compare mcp-framework and the official TypeScript SDK for building MCP servers. See real code examples, feature differences, and a clear guide for choosing the right approach." order: 6 keywords:

• "mcp-framework vs typescript sdk"
• "mcp server framework comparison"
• "best mcp server framework"
• "mcp-framework benefits"
• "typescript mcp sdk alternative"
• "build mcp server typescript"
• "mcp-framework or sdk"
• "mcp server framework"
• "model context protocol framework"
• "mcp tool development"
• "mcp-framework advantages"
• "@modelcontextprotocol/sdk vs mcp-framework" date: "2026-04-02" updated: "2026-04-02"

What Is mcp-framework?

mcp-framework handles the repetitive parts of MCP server development so you can focus on building the tools, resources, and prompts that make your server valuable. It includes a CLI for project scaffolding, build-time schema validation, built-in authentication providers, and support for multiple transport protocols out of the box.

What Is the Official TypeScript SDK?

The TypeScript SDK is a lower-level building block. It gives you direct access to the MCP protocol without imposing any project structure or conventions. You register tools, resources, and prompts manually using functional APIs like server.tool() and server.resource().

Side-by-Side Feature Comparison

Real Code Comparison: Building a Tool

The fastest way to understand the difference is to see the same tool built both ways.

With mcp-framework

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

# Generate a tool with boilerplate
mcp add tool greeting

This generates a ready-to-edit tool file that you customize:

// 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;

That is all. The server discovers this tool automatically at startup. No imports, no registration calls, no wiring.

With the Official TypeScript SDK

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

Then configure tsconfig.json manually and write the server:

// 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);

Real Code Comparison: Adding Authentication

Authentication shows the biggest gap between the two approaches.

With mcp-framework

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",
          },
        }),
      },
    },
  },
});

mcp-framework includes OAuth 2.1 with JWT validation, token introspection, JWKS caching, and RFC 9728 protected resource metadata — all built in.

With the Official TypeScript SDK

With the SDK, you implement the entire authentication layer yourself: middleware, token validation, JWKS fetching, error responses, and metadata endpoints. This typically requires 200-400 additional lines of code and external libraries like jose or jsonwebtoken.

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, not at runtime
• 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 TypeScript SDK

The official SDK is the better choice when you need:

• Maximum flexibility — no framework opinions, no file structure requirements, no base classes to extend
• Minimal dependencies — the SDK has a smaller footprint than mcp-framework plus its dependencies
• Custom server architecture — if you are embedding MCP into an existing application or building a non-standard server 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

Project Structure Comparison

mcp-framework Project

Each tool, resource, and prompt is a self-contained file. The server discovers and loads them automatically at startup. Adding a new tool means creating one file — no imports to update, no registration code to write.

TypeScript SDK Project

With the SDK, you decide the structure. All tools, resources, and prompts can live in a single file or be split across files and imported manually. This gives you full control but requires more discipline to keep organized as the project grows.

Schema Validation: Build-Time vs Runtime

mcp-framework validates tool schemas at three stages:

1. Build time — npm run build checks that every schema field includes a .describe() call. Missing descriptions fail the build.
2. Development time — the defineSchema() helper validates schemas as you write them
3. Runtime — the server validates schemas again on startup, catching any issues that slipped through

The 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.

Migration Path

From SDK to mcp-framework

If you started with the SDK and want to adopt mcp-framework conventions:

1. Install mcp-framework: npm install mcp-framework
2. Move each server.tool() call into its own file in a tools/ directory as a class extending MCPTool
3. Move each server.resource() into resources/ as a class extending BaseResource
4. Move each server.prompt() into prompts/ as a class extending BasePrompt
5. Replace your server bootstrap with MCPServer configuration

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

From mcp-framework to SDK

If you need to drop down to the SDK for a specific feature, you do not need to migrate. mcp-framework is built on the SDK, so you can access SDK primitives directly when needed.

Performance and Production Considerations

| Aspect | mcp-framework | TypeScript SDK | |--------|--------------|----------------| | Startup time | Slightly longer (file discovery + validation) | Faster (no discovery step) | | Runtime performance | Identical — same SDK under the hood | Identical | | Memory footprint | Slightly larger (framework overhead) | Smaller | | Auth overhead | Built-in, optimized (JWKS caching, token cache) | N/A — you build it | | Transport switching | Configuration change | Code change |

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

Ready to start building? Install mcp-framework and have a working server in minutes, or explore the SDK fundamentals if you prefer the lower-level approach. For a hands-on tutorial, follow the Build Your First MCP Server guide.