mcp-server

MCP Server Mastery

Project Setup

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

package.json

{
  "type": "module",
  "bin": { "my-mcp-server": "dist/index.js" },
  "scripts": { "build": "tsc", "start": "node dist/index.js" }
}

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext",
    "outDir": "dist", "strict": true, "esModuleInterop": true, "skipLibCheck": true
  },
  "include": ["src"]
}

Server Architecture

src/
├── index.ts           # Entry point, server + transport setup
├── tools/             # Tool handler files
│   ├── search.ts
│   └── compute.ts
├── resources/         # Resource handlers
│   └── config.ts
└── utils/             # Shared utilities
    └── errors.ts

Tool Patterns

Tool with Structured Output

import { McpServer } from "@modelcontextprotocol/server/mcp.js";
import { z } from "zod";

const server = new McpServer({ name: "my-server", version: "1.0.0" });

server.registerTool("calculate-bmi", {
  title: "BMI Calculator",
  description: "Calculate Body Mass Index from weight and height",
  inputSchema: z.object({
    weightKg: z.number().positive(),
    heightM: z.number().positive(),
  }),
  outputSchema: z.object({ bmi: z.number(), category: z.string() }),
}, async ({ weightKg, heightM }) => {
  const bmi = weightKg / (heightM * heightM);
  const category = bmi < 18.5 ? "underweight" : bmi < 25 ? "normal" : bmi < 30 ? "overweight" : "obese";
  return {
    content: [{ type: "text", text: `BMI: ${bmi.toFixed(1)} (${category})` }],
    structuredContent: { bmi: Number(bmi.toFixed(1)), category },
  };
});

Tool with Error Handling

server.registerTool("fetch-url", {
  title: "Fetch URL",
  description: "Fetch content from a URL and return as text",
  inputSchema: z.object({
    url: z.string().url(),
    timeout: z.number().optional().default(10000),
  }),
}, async ({ url, timeout }) => {
  try {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), timeout);
    const response = await fetch(url, { signal: controller.signal });
    clearTimeout(timer);

    if (!response.ok) {
      return { content: [{ type: "text", text: `HTTP ${response.status}: ${response.statusText}` }], isError: true };
    }

    const text = await response.text();
    return { content: [{ type: "text", text: text.slice(0, 50000) }] };
  } catch (error) {
    const message = error instanceof Error ? error.message : "Unknown error";
    return { content: [{ type: "text", text: `Fetch failed: ${message}` }], isError: true };
  }
});

Tool with Annotations

server.registerTool("read-file", {
  title: "Read File",
  description: "Read a file from disk",
  inputSchema: z.object({ path: z.string() }),
  annotations: { readOnlyHint: true, openWorldHint: false },
}, async ({ path }) => {
  const content = await fs.readFile(path, "utf-8");
  return { content: [{ type: "text", text: content }] };
});

Resource Patterns

Static Resource

server.registerResource("config", "config://app", {
  title: "App Configuration",
  description: "Current application configuration",
  mimeType: "application/json",
}, async (uri) => ({
  contents: [{ uri: uri.href, text: JSON.stringify(getConfig(), null, 2) }],
}));

Dynamic Resource with Template

import { ResourceTemplate } from "@modelcontextprotocol/server/mcp.js";

server.registerResource("user-profile",
  new ResourceTemplate("user://{userId}/profile", {
    list: async () => ({
      resources: users.map((u) => ({ uri: `user://${u.id}/profile`, name: u.name })),
    }),
  }),
  { title: "User Profile", mimeType: "application/json" },
  async (uri, { userId }) => ({
    contents: [{ uri: uri.href, text: JSON.stringify(await getUser(userId)) }],
  })
);

Transport Setup

Stdio (local CLI tools)

import { StdioServerTransport } from "@modelcontextprotocol/server/stdio.js";
const transport = new StdioServerTransport();
await server.connect(transport);

HTTP (remote services)

import express from "express";
import { NodeStreamableHTTPServerTransport } from "@modelcontextprotocol/server/streamableHttp.js";

const app = express();
app.use(express.json());

app.post("/mcp", async (req, res) => {
  const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(3000, "127.0.0.1");

Client Configuration

Claude Desktop / Cursor / VS Code

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["path/to/dist/index.js"],
      "env": { "API_KEY": "..." }
    }
  }
}

Best Practices

• Use Zod schemas for ALL input/output validation
• Keep tools focused — one action per tool
• Return isError: true on failures — never throw unhandled
• Log to stderr (console.error) — stdout is used by stdio transport
• Add #!/usr/bin/env node shebang for CLI distribution
• Resources are read-only — no mutations
• Use outputSchema when tools return structured data
• Set timeouts on all external calls