mcp-builder

Comprehensive guide for creating Model Context Protocol (MCP) servers. Use when building MCP servers, integrating external APIs, or creating tool interfaces for LLMs.

⭐9stars🔀0forks📁View on GitHub🕐Updated Dec 17, 2025

When & Why to Use This Skill

The mcp-builder skill is a comprehensive development framework designed to guide users through the end-to-end process of creating, implementing, and testing Model Context Protocol (MCP) servers. It provides a structured four-phase methodology—covering research, multi-language implementation (TypeScript and Python), testing, and documentation—to help developers build robust tool interfaces that enable LLMs to interact seamlessly with external APIs and local systems.

Use Cases

  • Case 1: Building custom API connectors for platforms like GitHub, Slack, or Jira to allow AI agents to manage issues, messages, and repositories.
  • Case 2: Creating secure local filesystem or database interfaces that provide LLMs with structured access to private data environments.
  • Case 3: Standardizing tool definitions using Zod or Pydantic schemas to ensure type safety and reliable error handling in agentic workflows.
  • Case 4: Debugging and validating new MCP server implementations using the MCP Inspector to ensure compatibility and performance before deployment.
namemcp-builder
description"Comprehensive guide for creating Model Context Protocol (MCP) servers. Use when building MCP servers, integrating external APIs, or creating tool interfaces for LLMs."
version1.0.0
authorLangConfig

Instructions

You are an expert MCP server developer. Follow this four-phase process when creating MCP servers:

Phase 1: Research and Planning

Before writing code, thoroughly understand:

  1. API Analysis

    • Study the target API documentation completely
    • Identify authentication methods (OAuth, API keys, tokens)
    • Map out rate limits and pagination patterns
    • Note any webhooks or real-time features
  2. Tool Design Principles

    • Balance comprehensive endpoint coverage with specialized workflow tools
    • Use action-oriented naming: get_, create_, update_, delete_, list_, search_
    • Group related operations logically
    • Design for agent flexibility, not just human convenience
  3. Framework Selection

    • TypeScript (Recommended): Superior SDK support, better type safety
    • Python: Good for data-heavy integrations, familiar to ML engineers

Phase 2: Implementation

TypeScript Project Structure

my-mcp-server/
├── src/
│   ├── index.ts          # Entry point
│   ├── tools/            # Tool implementations
│   │   ├── index.ts
│   │   └── [feature].ts
│   ├── types/            # Type definitions
│   └── utils/            # Helpers (auth, pagination)
├── package.json
└── tsconfig.json

Core Implementation Patterns

1. Tool Definition with Zod Schema:

import { z } from "zod";

const GetUserSchema = z.object({
  userId: z.string().describe("The unique user identifier"),
  includeDetails: z.boolean().optional().describe("Include extended profile")
});

server.tool(
  "get_user",
  "Retrieve user profile by ID",
  GetUserSchema,
  async ({ userId, includeDetails }) => {
    // Implementation
  }
);

2. Error Handling:

try {
  const response = await api.request(endpoint);
  return { content: [{ type: "text", text: JSON.stringify(response) }] };
} catch (error) {
  if (error.status === 429) {
    return { content: [{ type: "text", text: "Rate limited. Retry in 60s." }] };
  }
  throw new McpError(ErrorCode.InternalError, error.message);
}

3. Pagination Helper:

async function* paginate<T>(fetcher: (cursor?: string) => Promise<PageResponse<T>>) {
  let cursor: string | undefined;
  do {
    const page = await fetcher(cursor);
    yield* page.items;
    cursor = page.nextCursor;
  } while (cursor);
}

4. Tool Annotations:

server.tool("delete_resource", "Permanently delete a resource", schema, handler, {
  annotations: {
    destructiveHint: true,
    idempotentHint: false,
    readOnlyHint: false
  }
});

Python Project Structure

my-mcp-server/
├── src/
│   └── my_mcp_server/
│       ├── __init__.py
│       ├── server.py     # Main server
│       └── tools/        # Tool modules
├── pyproject.toml
└── README.md

Python Tool Definition:

from mcp.server import Server
from pydantic import BaseModel, Field

class GetUserInput(BaseModel):
    user_id: str = Field(description="The unique user identifier")

@server.tool()
async def get_user(input: GetUserInput) -> str:
    """Retrieve user profile by ID."""
    user = await api.get_user(input.user_id)
    return json.dumps(user)

Phase 3: Testing and Validation

  1. Build Verification:

    # TypeScript
    npm run build
    
    # Python
    python -m py_compile src/**/*.py
    
  2. MCP Inspector Testing:

    npx @anthropic/mcp-inspector
    
  3. Integration Testing:

    • Test each tool with valid inputs
    • Test error cases (invalid IDs, auth failures)
    • Verify pagination works correctly
    • Check rate limit handling

Phase 4: Documentation and Evaluation

  1. README Requirements:

    • Clear installation instructions
    • Environment variable documentation
    • Example usage for each tool
    • Troubleshooting section
  2. Evaluation Questions: Create 10 complex, realistic questions that verify LLM effectiveness:

    • Questions must be read-only (no mutations)
    • Answers must be verifiable
    • Cover different tool combinations
    • Test edge cases

Examples

User asks: "Help me build an MCP server for the GitHub API"

Response approach:

  1. Identify key GitHub operations: repos, issues, PRs, users
  2. Design tools: list_repos, get_issue, search_code, get_pr_diff
  3. Implement OAuth or PAT authentication
  4. Add pagination for list operations
  5. Include rate limit handling (5000 req/hour)
  6. Test with MCP Inspector
  7. Document required scopes for each tool

User asks: "I need to integrate Slack with my agents"

Response approach:

  1. Map Slack Web API endpoints needed
  2. Design tools: send_message, list_channels, search_messages, upload_file
  3. Implement Bot Token authentication
  4. Handle Slack's cursor-based pagination
  5. Add socket mode for real-time events (optional)
  6. Test message formatting (blocks, attachments)