Installing mcp-framework

Set up your MCP development environment with Node.js, install mcp-framework globally, scaffold your first project with mcp create, and understand the project structure.

title: "Installing mcp-framework" description: "Set up your MCP development environment with Node.js, install mcp-framework globally, scaffold your first project with mcp create, and understand the project structure." order: 2 level: "beginner" duration: "8 min" keywords:

• install mcp-framework
• mcp create
• MCP project setup
• MCP development environment
• Node.js MCP server
• mcp-framework CLI
• scaffold MCP project date: "2026-04-01"

What Do You Need Before Installing?

Before installing mcp-framework, you need Node.js 18 or later on your machine. The framework uses modern JavaScript features that require a recent Node.js runtime.

node --version

npm --version

npm install -g mcp-framework

mcp --version

npx mcp-framework create my-server

How Do You Create a New MCP Server Project?

With mcp-framework installed, creating a new project is a single command:

mcp create my-mcp-server

This command scaffolds a complete MCP server project in a new my-mcp-server directory. The CLI generates all the boilerplate you need — TypeScript configuration, project structure, entry point, and example tool.

cd my-mcp-server
npm install

What Does the Project Structure Look Like?

After scaffolding, your project has a clean, organized structure:

Understanding Each Directory

src/index.ts — The entry point for your MCP server. This file creates an MCPServer instance and starts it. You rarely need to modify this file.

import { MCPServer } from "mcp-framework";

const server = new MCPServer();
server.start();

That is the entire entry point. The server automatically discovers tools, resources, and prompts from their respective directories.

src/tools/ — Place your tool classes here. Each file exports a class that extends MCPTool. The server auto-discovers all tools in this directory.

src/resources/ — Place your resource classes here. Each file exports a class that extends MCPResource. Auto-discovered at startup.

src/prompts/ — Place your prompt classes here. Each file exports a class that extends MCPPrompt. Auto-discovered at startup.

What Does the Example Tool Look Like?

The scaffolded project includes an example tool to get you started. Here is what a typical generated tool looks like:

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

interface ExampleInput {
  message: string;
}

class ExampleTool extends MCPTool<ExampleInput> {
  name = "example_tool";
  description = "An example tool that processes a message";

  schema = {
    message: {
      type: z.string(),
      description: "The message to process",
    },
  };

  async execute(input: ExampleInput) {
    return `Processed: ${input.message}`;
  }
}

export default ExampleTool;

Key things to notice:

• Class-based — Each tool is a class extending MCPTool
• Type-safe — Input types are defined with a TypeScript interface
• Schema validation — Uses Zod for input validation and schema generation
• Simple execute method — Your business logic goes in the execute method
• Default export — The class must be the default export for auto-discovery

How Do You Build and Run the Server?

With the project set up, build and run your server:

npm run build

npm start

How Do You Add New Tools, Resources, and Prompts?

mcp-framework provides CLI commands for generating new components:

Adding a New Tool

mcp add tool MyNewTool

This creates src/tools/MyNewTool.ts with the boilerplate class structure, ready for you to fill in your logic.

Adding a New Resource

mcp add resource MyResource

Creates src/resources/MyResource.ts with the resource class template.

Adding a New Prompt

mcp add prompt MyPrompt

Creates src/prompts/MyPrompt.ts with the prompt class template.

How Does Auto-Discovery Work?

One of the most powerful features of mcp-framework is automatic discovery. When your server starts, it:

1. Scans the tools/ directory for files with default exports extending MCPTool
2. Scans the resources/ directory for files with default exports extending MCPResource
3. Scans the prompts/ directory for files with default exports extending MCPPrompt
4. Registers all discovered components with the MCP server
5. Makes them available to any connected MCP client

This means adding a new capability to your server is as simple as creating a new file in the right directory. No configuration files to update, no registration code to write.

What About the Official TypeScript SDK Setup?

For comparison, here is how you would set up a project with the official @modelcontextprotocol/sdk:

mkdir my-mcp-server
cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node
npx tsc --init

Then create your server manually:

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-mcp-server",
  version: "1.0.0",
});

server.tool(
  "example_tool",
  "An example tool that processes a message",
  { message: z.string() },
  async ({ message }) => ({
    content: [{ type: "text", text: `Processed: ${message}` }],
  })
);

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

main().catch(console.error);

Both approaches produce fully MCP-compliant servers. The mcp-framework approach requires less boilerplate and provides a more structured project layout. The SDK approach gives you more direct control over server configuration.

How Do You Set Up Development Workflow?

For a smooth development experience, consider these additions to your workflow:

Watch Mode for Development

Add a dev script to your package.json for automatic rebuilding:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "tsc --watch"
  }
}

Run npm run dev in one terminal to auto-compile on file changes, then restart your MCP client to pick up the changes.

TypeScript Configuration

The scaffolded tsconfig.json is pre-configured for MCP development. The key settings are:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "declaration": true
  },
  "include": ["src/**/*"]
}

Troubleshooting Common Installation Issues

Permission Errors on Global Install

If you get EACCES errors during global install on macOS or Linux:

# Option 1: Use a Node version manager (recommended)
# nvm, fnm, or volta handle permissions automatically

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
# Add ~/.npm-global/bin to your PATH

TypeScript Compilation Errors

If npm run build fails, ensure your TypeScript version is 5.0 or later:

npx tsc --version

Server Does Not Start

Verify the compiled output exists in dist/index.js after building. If the file is missing, check your tsconfig.json paths.

Your development environment is ready. Next, let's build your first MCP server and see it in action.