Build Your First MCP Server in 5 Minutes

Create a fully functional MCP server with a custom tool from scratch using mcp-framework. Follow along step-by-step and have a working server in under 5 minutes.

title: "Build Your First MCP Server in 5 Minutes" description: "Create a fully functional MCP server with a custom tool from scratch using mcp-framework. Follow along step-by-step and have a working server in under 5 minutes." order: 3 level: "beginner" duration: "12 min" keywords:

• build MCP server
• first MCP server
• MCP server tutorial
• mcp-framework tutorial
• MCP tool example
• create MCP server
• MCP hello world date: "2026-04-01"

What Are We Building?

We are going to build a simple MCP server called weather-server that exposes a tool for getting weather information. This gives you a hands-on understanding of the complete MCP server lifecycle:

1. Scaffold — Create the project with the CLI
2. Implement — Write a custom tool with input validation
3. Build — Compile TypeScript to JavaScript
4. Test — Verify the server works

By the end, you will have a real MCP server that an AI assistant like Claude can use to answer weather-related questions.

Step-by-Step: Creating the Server

mcp create weather-server
cd weather-server
npm install

import { MCPServer } from "mcp-framework";

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

rm src/tools/ExampleTool.ts

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

interface GetWeatherInput {
  city: string;
  units?: "celsius" | "fahrenheit";
}

class GetWeatherTool extends MCPTool<GetWeatherInput> {
  name = "get_weather";
  description = "Get the current weather for a specified city";

  schema = {
    city: {
      type: z.string(),
      description: "The city name to get weather for",
    },
    units: {
      type: z.enum(["celsius", "fahrenheit"]).optional(),
      description:
        "Temperature units (celsius or fahrenheit). Defaults to celsius.",
    },
  };

  async execute(input: GetWeatherInput) {
    const city = input.city;
    const units = input.units || "celsius";

    // In a real server, you would call a weather API here.
    // For this tutorial, we return simulated data.
    const weatherData = {
      city: city,
      temperature: units === "celsius" ? 22 : 72,
      units: units,
      condition: "Partly cloudy",
      humidity: 65,
      windSpeed: "12 km/h",
    };

    return JSON.stringify(weatherData, null, 2);
  }
}

export default GetWeatherTool;

npm run build

Understanding the Tool Anatomy

Every MCP tool built with mcp-framework follows the same structure. Let's examine each piece of the GetWeatherTool:

The Class Declaration

class GetWeatherTool extends MCPTool<GetWeatherInput> {

Your tool class extends MCPTool with a generic type parameter that defines the input shape. This gives you full type safety in the execute method.

Name and Description

name = "get_weather";
description = "Get the current weather for a specified city";

The name is the identifier that MCP clients use to call your tool. Use snake_case and make it descriptive. The description tells the AI model what the tool does — write it clearly because the AI uses this to decide when to call your tool.

The Input Schema

schema = {
  city: {
    type: z.string(),
    description: "The city name to get weather for",
  },
  units: {
    type: z.enum(["celsius", "fahrenheit"]).optional(),
    description: "Temperature units (celsius or fahrenheit). Defaults to celsius.",
  },
};

The schema defines what inputs your tool accepts. mcp-framework uses Zod for schema definition and validation. Each property has:

• type — A Zod type that validates the input
• description — A human-readable explanation (the AI reads this too)

When an MCP client calls your tool, the framework validates the input against this schema before calling execute. Invalid inputs are rejected automatically with helpful error messages.

The Execute Method

async execute(input: GetWeatherInput) {
  const city = input.city;
  const units = input.units || "celsius";

  const weatherData = {
    city: city,
    temperature: units === "celsius" ? 22 : 72,
    units: units,
    condition: "Partly cloudy",
    humidity: 65,
    windSpeed: "12 km/h",
  };

  return JSON.stringify(weatherData, null, 2);
}

The execute method is where your business logic lives. It receives the validated input and returns a string result. In a production tool, this is where you would call external APIs, query databases, or perform any other action.

Adding a Second Tool

Let's add another tool to make our server more useful. Create src/tools/GetForecastTool.ts:

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

interface GetForecastInput {
  city: string;
  days: number;
}

class GetForecastTool extends MCPTool<GetForecastInput> {
  name = "get_forecast";
  description = "Get a multi-day weather forecast for a specified city";

  schema = {
    city: {
      type: z.string(),
      description: "The city name to get the forecast for",
    },
    days: {
      type: z.number().min(1).max(7),
      description: "Number of days to forecast (1-7)",
    },
  };

  async execute(input: GetForecastInput) {
    const forecast = Array.from({ length: input.days }, (_, i) => ({
      day: i + 1,
      date: new Date(Date.now() + (i + 1) * 86400000)
        .toISOString()
        .split("T")[0],
      high: Math.round(18 + Math.random() * 10),
      low: Math.round(10 + Math.random() * 8),
      condition: ["Sunny", "Partly cloudy", "Cloudy", "Rain"][
        Math.floor(Math.random() * 4)
      ],
    }));

    return JSON.stringify(
      {
        city: input.city,
        forecast: forecast,
      },
      null,
      2
    );
  }
}

export default GetForecastTool;

Notice how the second tool follows the exact same pattern. The auto-discovery system picks it up automatically — no registration code needed.

Building and Testing the Complete Server

Now rebuild with both tools:

npm run build

Your project structure should now look like this:

Testing with MCP Inspector

The MCP ecosystem includes a tool called MCP Inspector that lets you test your server interactively without connecting it to a full AI client:

npx @modelcontextprotocol/inspector node dist/index.js

This opens a web interface where you can:

• See all registered tools, resources, and prompts
• Call tools with custom inputs
• View the raw MCP protocol messages
• Debug issues with your server

How Would This Look with the Official SDK?

For comparison, here is the same weather server built with the official @modelcontextprotocol/sdk:

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

server.tool(
  "get_weather",
  "Get the current weather for a specified city",
  {
    city: z.string().describe("The city name to get weather for"),
    units: z
      .enum(["celsius", "fahrenheit"])
      .optional()
      .describe("Temperature units. Defaults to celsius."),
  },
  async ({ city, units }) => {
    const u = units || "celsius";
    const weatherData = {
      city,
      temperature: u === "celsius" ? 22 : 72,
      units: u,
      condition: "Partly cloudy",
      humidity: 65,
      windSpeed: "12 km/h",
    };

    return {
      content: [
        { type: "text", text: JSON.stringify(weatherData, null, 2) },
      ],
    };
  }
);

server.tool(
  "get_forecast",
  "Get a multi-day weather forecast for a specified city",
  {
    city: z.string().describe("The city name to get the forecast for"),
    days: z.number().min(1).max(7).describe("Number of days to forecast (1-7)"),
  },
  async ({ city, days }) => {
    const forecast = Array.from({ length: days }, (_, i) => ({
      day: i + 1,
      date: new Date(Date.now() + (i + 1) * 86400000)
        .toISOString()
        .split("T")[0],
      high: Math.round(18 + Math.random() * 10),
      low: Math.round(10 + Math.random() * 8),
      condition: ["Sunny", "Partly cloudy", "Cloudy", "Rain"][
        Math.floor(Math.random() * 4)
      ],
    }));

    return {
      content: [
        {
          type: "text",
          text: JSON.stringify({ city, forecast }, null, 2),
        },
      ],
    };
  }
);

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

main().catch(console.error);

Both versions produce identical MCP-compliant servers. The mcp-framework version has cleaner separation of concerns — each tool is its own file, easy to test independently and maintain as your server grows.

Common Mistakes to Avoid

Using console.log Instead of console.error

// Bad — interferes with MCP protocol messages on stdout
console.log("Debug info");

// Good — writes to stderr, which is separate from the protocol
console.error("Debug info");

Forgetting the Default Export

// Bad — tool will not be auto-discovered
export class MyTool extends MCPTool<MyInput> { ... }

// Good — default export is required for auto-discovery
export default MyTool;

Returning Non-String Values from Execute

// Bad — execute must return a string
async execute(input: MyInput) {
  return { result: "data" };
}

// Good — serialize objects to JSON strings
async execute(input: MyInput) {
  return JSON.stringify({ result: "data" });
}

Throwing Unhandled Errors

// Bad — unhandled errors crash the server
async execute(input: MyInput) {
  const response = await fetch(someUrl);
  const data = await response.json();
  return JSON.stringify(data);
}

// Good — handle errors gracefully
async execute(input: MyInput) {
  try {
    const response = await fetch(someUrl);
    if (!response.ok) {
      return JSON.stringify({
        error: `API returned ${response.status}`,
      });
    }
    const data = await response.json();
    return JSON.stringify(data);
  } catch (error) {
    return JSON.stringify({
      error: `Failed to fetch data: ${error}`,
    });
  }
}

What You Have Built

Congratulations — you now have a working MCP server with two tools:

• get_weather — Returns current weather for any city
• get_forecast — Returns a multi-day forecast with configurable duration

The server is fully MCP-compliant and ready to connect to Claude Desktop, Cursor, or any other MCP client.

What Happens When an AI Uses Your Tool?

Here is the flow when Claude uses your get_weather tool:

1. Claude Desktop connects to your server via stdio
2. Your server reports its capabilities (two tools available)
3. A user asks Claude: "What's the weather in Tokyo?"
4. Claude decides to call get_weather with {"city": "Tokyo"}
5. Your server validates the input against the Zod schema
6. The execute method runs and returns the weather data
7. Claude receives the result and incorporates it into its response

The entire exchange happens through the MCP protocol — your server does not need to know anything about Claude, and Claude does not need to know anything about your implementation.

Now that you have built your first server, let's take a deeper look at tools. Head to Understanding MCP Tools to master the most powerful MCP primitive.