---
name: mcp-builder
description: Guide for creating high-quality MCP servers enabling LLMs to interact with external services
version: 1.0.0
author: Anthropic (adapted)
platforms: [claude-code, cursor]
license: Apache-2.0
source: https://github.com/anthropics/skills
---

# MCP Server Builder

Build production-ready MCP (Model Context Protocol) servers that integrate external APIs with LLM agents.

## 4-Phase Development Workflow

### Phase 1: Research & Planning
- Study the MCP specification at https://modelcontextprotocol.io
- Analyze the target API: authentication, rate limits, key operations
- Choose TypeScript (recommended) or Python (FastMCP)
- Plan tool names, inputs, and outputs before coding

### Phase 2: Implementation
```typescript
// Tool definition pattern
server.tool(
  "tool-name",
  "Clear description of what this tool does",
  {
    param: z.string().describe("Parameter description"),
  },
  async ({ param }) => {
    // Implementation
    return { content: [{ type: "text", text: result }] };
  }
);
```

Key implementation rules:
- Use Zod schemas for all input validation
- Add `outputSchema` for structured outputs
- Use tool annotations (`readOnly`, `destructive`) appropriately
- Prefer stateless JSON over stateful sessions for remote servers

### Phase 3: Testing
- Use MCP Inspector (`npx @modelcontextprotocol/inspector`)
- Test every tool manually before integration
- Verify error messages are helpful to the LLM

### Phase 4: Create Evaluations
Generate 10 XML-formatted test cases:
```xml
<eval>
  <prompt>User request that exercises multiple tools</prompt>
  <expected>What correct execution looks like</expected>
</eval>
```

## Project Structure
```
my-mcp-server/
├── src/
│   ├── index.ts          # Server entry point
│   ├── tools/            # Tool implementations
│   └── types.ts          # Shared types
├── evals/                # Test cases
├── package.json
└── README.md
```