How to build an MCP server

To build an MCP server, you define a set of named tools with typed parameters, implement their logic, and connect them to the MCP SDK. The SDK handles all protocol communication. You can have a working server in under an hour.

New to MCP? Start with What is an MCP server? before diving into building one.

What are you building?

An MCP server is a Node.js (or Python) process that:

1. Connects to a data source or API
2. Exposes a set of tools with names, descriptions, and parameter schemas
3. Handles requests from an AI client over stdio (or HTTP)
4. Returns structured responses

The official TypeScript SDK handles the protocol layer. You only need to define your tools and implement their logic.

This guide uses TypeScript. Want to skip the manual setup? mcp-creator-typescript scaffolds a complete TypeScript MCP server conversationally. See the TypeScript MCP Creator guide.

If you prefer Python, use the FastMCP framework or mcp-creator-python for the automated path. See How to publish your MCP server to PyPI for the full Python process.

What do I need to build an MCP server?

• Node.js 18+
• TypeScript (recommended)
• An API or data source you want to expose

Step 1: Initialize your project

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

Create a tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "strict": true
  },
  "include": ["src"]
}

Step 2: Create the server

Create src/index.ts:

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

// Define a tool
server.tool(
  "get_weather",
  "Get the current weather for a city",
  {
    city: z.string().describe("The city name"),
    units: z.enum(["celsius", "fahrenheit"]).optional().default("celsius"),
  },
  async ({ city, units }) => {
    // Call your API here
    const data = await fetchWeather(city, units);

    return {
      content: [
        {
          type: "text",
          text: `Weather in ${city}: ${data.temperature}° ${units}, ${data.description}`,
        },
      ],
    };
  }
);

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

Step 3: Implement your tool logic

Replace fetchWeather with your actual API call. The tool function receives validated parameters (typed by Zod) and returns a content array.

For structured data, you can return JSON:

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

For errors, throw and the SDK will format them correctly:

if (!response.ok) {
  throw new Error(`API error: ${response.statusText}`);
}

Step 4: Test locally

Add to your package.json:

{
  "scripts": {
    "dev": "tsx src/index.ts"
  }
}

Then add it to your Claude Desktop config:

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/my-mcp-server/src/index.ts"]
    }
  }
}

Restart Claude Desktop and test your tools.

Step 5: Ship it

Package your server for distribution:

npm run build

Publish to npm (or PyPI for Python servers) and submit to MCP Marketplace to get it listed, security-checked, and discoverable by thousands of users.

Want to charge for your server? Learn about license keys, remote hosting, and the freemium model.

Prefer a faster path with AI assistance? The MCP Creator tools scaffold a complete server in minutes: TypeScript or Python.

What makes a good MCP server?

Write clear tool descriptions. The AI uses these descriptions to decide when to call your tool. "Get the current weather for a location" is better than "weather tool".

Use Zod for parameters. It validates input automatically and generates schemas the AI can use to call your tool correctly.

Keep tools focused. One tool, one action. get_user and update_user are better than a single manage_user with a mode parameter.

Handle credentials via environment variables. Never hardcode API keys. Document what credentials are needed in your README.

Read the full MCP SDK documentation for advanced features including resources, prompts, and sampling.