mcp-server-build

Build an MCP Server

Samples below are minimal but complete: each one runs.

TypeScript

npm install @modelcontextprotocol/sdk zod

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(
  "list_items",
  "List items with pagination. Use before acting on a specific item.",
  { page: z.number().default(1), limit: z.number().max(100).default(20) },
  async ({ page, limit }) => {
    try {
      const items = await api.listItems({ page, limit });
      return {
        content: [{
          type: "text",
          text: JSON.stringify({ items, page, hasMore: items.length === limit }),
        }],
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error: ${error.message}. Try: check API key, verify endpoint, reduce page size.`,
        }],
        isError: true,
      };
    }
  },
);

await server.connect(new StdioServerTransport());

Python

pip install mcp

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("my-mcp-server")

class ListParams(BaseModel):
    page: int = Field(default=1, description="1-based page number")
    limit: int = Field(default=20, le=100, description="Items per page, max 100")

@mcp.tool(description="List items with pagination. Use before acting on one.")
async def list_items(params: ListParams) -> dict:
    items = await api.list_items(page=params.page, limit=params.limit)
    return {"items": items, "page": params.page, "hasMore": len(items) == params.limit}

if __name__ == "__main__":
    mcp.run()

FastMCP turns the Pydantic model into the input schema, so field descriptions and constraints reach the agent. Put the constraint in the model rather than validating by hand in the body.