MCP Tutorial: Build Your First Model Context Protocol Server (2026)

# Create project directory
mkdir my-mcp-server && cd my-mcp-server

# Initialize npm project
npm init -y

# Install MCP SDK and TypeScript
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node tsx

# Initialize TypeScript config
npx tsc --init --target ES2022 --module Node16 \
  --moduleResolution Node16 --outDir dist

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

// Expose a static resource
server.resource(
  "project-readme",
  "file://readme",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: "# My Project\nThis is the project README.",
      mimeType: "text/markdown",
    }],
  })
);

// Expose a dynamic resource (e.g., system info)
server.resource(
  "system-info",
  "system://info",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: JSON.stringify({
        platform: process.platform,
        nodeVersion: process.version,
        uptime: process.uptime(),
        memoryUsage: process.memoryUsage().heapUsed,
      }, null, 2),
      mimeType: "application/json",
    }],
  })
);

// Add tools to the same server instance

// Tool: Search notes
server.tool(
  "search-notes",
  "Search through saved notes by keyword",
  { query: z.string().describe("Search keyword") },
  async ({ query }) => {
    const notes = [
      { id: 1, title: "Meeting notes", content: "Discussed Q3 roadmap and hiring plan" },
      { id: 2, title: "Architecture decision", content: "Moving to event-driven architecture" },
      { id: 3, title: "Bug report", content: "Memory leak in the connection pool" },
    ];
    const matches = notes.filter(
      (n) => n.title.toLowerCase().includes(query.toLowerCase()) ||
             n.content.toLowerCase().includes(query.toLowerCase())
    );
    return {
      content: [{
        type: "text" as const,
        text: matches.length > 0
          ? JSON.stringify(matches, null, 2)
          : `No notes found matching "${query}"`,
      }],
    };
  }
);

// Tool: Create a note
server.tool(
  "create-note",
  "Create a new note with a title and content",
  {
    title: z.string().describe("Note title"),
    content: z.string().describe("Note content"),
  },
  async ({ title, content }) => {
    // In a real app, save to a database
    const id = Date.now();
    return {
      content: [{
        type: "text" as const,
        text: `Note created successfully: { id: ${id}, title: "${title}" }`,
      }],
    };
  }
);

// Tool: Get current weather (external API example)
server.tool(
  "get-weather",
  "Get current weather for a city",
  { city: z.string().describe("City name") },
  async ({ city }) => {
    // Replace with a real weather API call
    const mockWeather = {
      city,
      temperature: "22°C",
      condition: "Partly cloudy",
      humidity: "65%",
    };
    return {
      content: [{
        type: "text" as const,
        text: JSON.stringify(mockWeather, null, 2),
      }],
    };
  }
);

// Add the transport and start the server (bottom of src/index.ts)

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP server running on stdio");
}

main().catch(console.error);

// Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
// Claude Code: ~/.claude/claude_code_config.json (or project-level .mcp.json)
{
  "mcpServers": {
    "my-first-server": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/my-mcp-server/src/index.ts"]
    }
  }
}