mcp-builder

MCP Server Development Guide

Create MCP servers that enable LLMs to interact with external services through well-designed tools.

High-Level Workflow

Phase 1: Research and Planning

Understand Modern MCP Design:

• Balance comprehensive API coverage with specialized workflow tools
• Use clear, descriptive tool names with consistent prefixes (e.g., github_create_issue)
• Design tools that return focused, relevant data
• Provide actionable error messages

Study MCP Protocol:

• Start with sitemap: https://modelcontextprotocol.io/sitemap.xml
• Key pages: specification, transport mechanisms, tool definitions

Phase 2: Implementation

Recommended Stack:

• Language: TypeScript (best SDK support)
• Transport: Streamable HTTP for remote, stdio for local

Project Structure:

my-mcp-server/
├── src/
│   ├── index.ts      # Server entry point
│   ├── tools/        # Tool implementations
│   └── utils/        # Shared utilities
├── package.json
└── tsconfig.json

Tool Implementation Pattern:

server.registerTool({
  name: "github_create_issue",
  description: "Create a new GitHub issue",
  inputSchema: z.object({
    repo: z.string().describe("Repository name (owner/repo)"),
    title: z.string().describe("Issue title"),
    body: z.string().optional().describe("Issue body"),
  }),
  outputSchema: z.object({
    id: z.number(),
    url: z.string(),
  }),
  annotations: {
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,
  },
  handler: async (input) => {
    // Implementation
    return { id: 123, url: "https://..." };
  },
});

Phase 3: Test

# TypeScript
npm run build
npx @modelcontextprotocol/inspector

# Python
python -m py_compile your_server.py

Phase 4: Create Evaluations

Create 10 complex, realistic questions to test your MCP server:

<evaluation>
  <qa_pair>
    <question>Find all open issues labeled 'bug' in the repo</question>
    <answer>5</answer>
  </qa_pair>
</evaluation>

Tool Design Best Practices

• Use Zod (TS) or Pydantic (Python) for schemas
• Include constraints and examples in field descriptions
• Define outputSchema for structured data
• Support pagination where applicable
• Add tool annotations (readOnly, destructive, idempotent)