> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/anthropics/skills/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Builder

> Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools

## Overview

The MCP Builder skill helps you create Model Context Protocol (MCP) servers that enable LLMs to interact with external services through well-designed tools. The quality of an MCP server is measured by how well it enables LLMs to accomplish real-world tasks.

<Note>
  **Recommended Stack**: TypeScript with streamable HTTP transport for remote servers, stdio for local servers. TypeScript offers high-quality SDK support and excellent compatibility across execution environments.
</Note>

## When to Use This Skill

Use the MCP Builder skill when you need to:

* Build MCP servers to integrate external APIs or services
* Create tools for LLMs to interact with third-party platforms
* Develop workflow automation through MCP protocol
* Support both Python (FastMCP) and Node/TypeScript (MCP SDK) implementations

## Development Workflow

Creating a high-quality MCP server involves four main phases:

<Steps>
  <Step title="Deep Research and Planning">
    Understanding MCP design principles, studying protocol documentation, reviewing framework docs, and planning your implementation.
  </Step>

  <Step title="Implementation">
    Setting up project structure, implementing core infrastructure, and building individual tools with proper schemas and error handling.
  </Step>

  <Step title="Review and Test">
    Ensuring code quality, running builds, and testing with MCP Inspector to verify functionality.
  </Step>

  <Step title="Create Evaluations">
    Developing comprehensive test cases to verify that LLMs can effectively use your MCP server for realistic tasks.
  </Step>
</Steps>

## Core Design Principles

### API Coverage vs. Workflow Tools

Balance comprehensive API endpoint coverage with specialized workflow tools. While workflow tools can be more convenient for specific tasks, comprehensive coverage gives agents flexibility to compose operations.

<Accordion title="Best Practice: Prioritize Comprehensive Coverage">
  When uncertain, prioritize comprehensive API coverage. Performance varies by client—some benefit from code execution that combines basic tools, while others work better with higher-level workflows.
</Accordion>

### Tool Naming and Discoverability

Clear, descriptive tool names help agents find the right tools quickly:

* Use consistent prefixes (e.g., `github_create_issue`, `github_list_repos`)
* Follow action-oriented naming conventions
* Make tool purposes immediately obvious from the name

### Context Management

Agents benefit from concise tool descriptions and the ability to filter/paginate results:

* Design tools that return focused, relevant data
* Support pagination for large result sets
* Provide filtering options where appropriate
* Some clients support code execution for efficient data processing

### Actionable Error Messages

Error messages should guide agents toward solutions:

* Include specific suggestions for fixing issues
* Provide clear next steps
* Reference documentation when relevant
* Indicate required permissions or authentication

## Phase 1: Deep Research and Planning

### Study MCP Protocol Documentation

Start by understanding the official specification:

1. Navigate the sitemap: `https://modelcontextprotocol.io/sitemap.xml`
2. Fetch specific pages with `.md` suffix for markdown format
3. Review key pages:
   * Specification overview and architecture
   * Transport mechanisms (streamable HTTP, stdio)
   * Tool, resource, and prompt definitions

### Study Framework Documentation

<Tabs>
  <Tab title="TypeScript (Recommended)">
    **Why TypeScript?**

    * High-quality SDK support
    * Good compatibility in execution environments (e.g., MCPB)
    * AI models excel at generating TypeScript code
    * Benefits from broad usage, static typing, and good linting tools

    **Resources:**

    * TypeScript SDK: `https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md`
    * Use streamable HTTP for remote servers (stateless JSON)
    * Use stdio for local servers
  </Tab>

  <Tab title="Python">
    **Python SDK:**

    * Load documentation from: `https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md`
    * FastMCP framework provides simplified development
    * Good for local integrations and prototyping
  </Tab>
</Tabs>

### Plan Your Implementation

**Understand the API:**

* Review the service's API documentation
* Identify key endpoints and authentication requirements
* Map data models and response structures

**Tool Selection:**

* Prioritize comprehensive API coverage
* List endpoints to implement, starting with most common operations
* Consider workflow tools for complex multi-step operations

## Phase 2: Implementation

### Project Structure Setup

<Tabs>
  <Tab title="TypeScript">
    ```json theme={null}
    // package.json example
    {
      "name": "mcp-server-example",
      "version": "1.0.0",
      "type": "module",
      "dependencies": {
        "@modelcontextprotocol/sdk": "latest"
      }
    }
    ```

    ```json theme={null}
    // tsconfig.json
    {
      "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "moduleResolution": "node",
        "strict": true
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    # Project structure
    my_mcp_server/
    ├── __init__.py
    ├── server.py
    ├── tools/
    │   ├── __init__.py
    │   └── api_tools.py
    └── requirements.txt
    ```

    ```txt theme={null}
    # requirements.txt
    mcp
    pydantic
    httpx
    ```
  </Tab>
</Tabs>

### Core Infrastructure

Create shared utilities:

* **API client** with authentication
* **Error handling** helpers
* **Response formatting** (JSON/Markdown)
* **Pagination support** for large datasets

### Implementing Tools

For each tool, follow these guidelines:

<Accordion title="Input Schema">
  Use Zod (TypeScript) or Pydantic (Python) for validation:

  ```typescript theme={null}
  // TypeScript with Zod
  import { z } from 'zod';

  const CreateIssueInput = z.object({
    title: z.string().describe('Issue title'),
    body: z.string().optional().describe('Issue description'),
    labels: z.array(z.string()).optional().describe('Labels to apply')
  });
  ```

  ```python theme={null}
  # Python with Pydantic
  from pydantic import BaseModel, Field

  class CreateIssueInput(BaseModel):
      title: str = Field(description="Issue title")
      body: str | None = Field(None, description="Issue description")
      labels: list[str] | None = Field(None, description="Labels to apply")
  ```
</Accordion>

<Accordion title="Output Schema">
  Define `outputSchema` where possible for structured data:

  * Use `structuredContent` in tool responses (TypeScript SDK feature)
  * Helps clients understand and process tool outputs
  * Enables better agent reasoning about results
</Accordion>

<Accordion title="Tool Implementation">
  Best practices:

  * Use async/await for I/O operations
  * Implement proper error handling with actionable messages
  * Support pagination where applicable
  * Return both text content and structured data when using modern SDKs

  **Tool Annotations:**

  * `readOnlyHint`: true/false (does this tool modify data?)
  * `destructiveHint`: true/false (could this cause data loss?)
  * `idempotentHint`: true/false (safe to retry?)
  * `openWorldHint`: true/false (accesses external resources?)
</Accordion>

### Example Tool Implementation

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    server.registerTool({
      name: 'github_create_issue',
      description: 'Create a new GitHub issue',
      inputSchema: zodToJsonSchema(CreateIssueInput),
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false
      },
      handler: async (args) => {
        const { title, body, labels } = args;
        
        try {
          const response = await githubClient.createIssue({
            title,
            body,
            labels
          });
          
          return {
            content: [
              {
                type: 'text',
                text: `Created issue #${response.number}: ${response.html_url}`
              }
            ]
          };
        } catch (error) {
          throw new Error(
            `Failed to create issue: ${error.message}. ` +
            `Check repository permissions and authentication.`
          );
        }
      }
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    @mcp.tool()
    async def github_create_issue(
        title: str,
        body: str | None = None,
        labels: list[str] | None = None
    ) -> str:
        """Create a new GitHub issue.
        
        Args:
            title: Issue title
            body: Issue description
            labels: Labels to apply
        """
        try:
            response = await github_client.create_issue(
                title=title,
                body=body,
                labels=labels
            )
            return f"Created issue #{response.number}: {response.html_url}"
        except Exception as e:
            raise ValueError(
                f"Failed to create issue: {str(e)}. "
                "Check repository permissions and authentication."
            )
    ```
  </Tab>
</Tabs>

## Phase 3: Review and Test

### Code Quality Checklist

Review your implementation for:

* No duplicated code (DRY principle)
* Consistent error handling patterns
* Full type coverage (TypeScript) or type hints (Python)
* Clear, concise tool descriptions
* Proper input validation
* Actionable error messages

### Build and Test

<Tabs>
  <Tab title="TypeScript">
    ```bash theme={null}
    # Verify compilation
    npm run build

    # Test with MCP Inspector
    npx @modelcontextprotocol/inspector
    ```
  </Tab>

  <Tab title="Python">
    ```bash theme={null}
    # Verify syntax
    python -m py_compile your_server.py

    # Test with MCP Inspector
    mcp dev your_server.py
    ```
  </Tab>
</Tabs>

## Phase 4: Create Evaluations

After implementing your MCP server, create comprehensive evaluations to test its effectiveness.

### Evaluation Purpose

Use evaluations to test whether LLMs can effectively use your MCP server to answer realistic, complex questions.

### Creating Effective Evaluations

<Steps>
  <Step title="Tool Inspection">
    List available tools and understand their capabilities
  </Step>

  <Step title="Content Exploration">
    Use READ-ONLY operations to explore available data
  </Step>

  <Step title="Question Generation">
    Create 10 complex, realistic questions
  </Step>

  <Step title="Answer Verification">
    Solve each question yourself to verify answers
  </Step>
</Steps>

### Evaluation Requirements

Ensure each question is:

* **Independent**: Not dependent on other questions
* **Read-only**: Only non-destructive operations required
* **Complex**: Requiring multiple tool calls and deep exploration
* **Realistic**: Based on real use cases humans would care about
* **Verifiable**: Single, clear answer that can be verified by string comparison
* **Stable**: Answer won't change over time

### Evaluation Format

```xml theme={null}
<evaluation>
  <qa_pair>
    <question>
      Find discussions about AI model launches with animal codenames. 
      One model needed a specific safety designation that uses the format ASL-X. 
      What number X was being determined for the model named after a spotted wild cat?
    </question>
    <answer>3</answer>
  </qa_pair>
  <qa_pair>
    <question>Your complex question here...</question>
    <answer>Verifiable answer</answer>
  </qa_pair>
  <!-- More qa_pairs... -->
</evaluation>
```

## Best Practices Summary

<Note>
  **Key Takeaways:**

  1. Prioritize comprehensive API coverage over limited workflow tools
  2. Use clear, consistent naming conventions with prefixes
  3. Implement proper error handling with actionable messages
  4. Define input/output schemas for all tools
  5. Add appropriate tool annotations (readOnly, destructive, etc.)
  6. Test thoroughly with MCP Inspector
  7. Create realistic evaluations with verifiable answers
</Note>

## Transport Selection

* **Streamable HTTP**: For remote servers (simpler to scale and maintain)
* **stdio**: For local servers (direct process communication)

Streamable HTTP uses stateless JSON, making it easier to scale and maintain compared to stateful sessions and streaming responses.

## Additional Resources

The skill includes reference files for:

* **MCP Best Practices**: Core guidelines for server and tool design
* **Python Implementation Guide**: Complete FastMCP patterns and examples
* **TypeScript Implementation Guide**: Complete SDK patterns and examples
* **Evaluation Guide**: Comprehensive evaluation creation strategies