/mcp-builder

name: mcp-builder
description: "Build MCP servers in Python with FastMCP. Define tools / resources / prompts, build the server, test locally, deploy to FastMCP Cloud or Docker. Use whenever the user mentions building an MCP server, exposing tools to LLMs, FastMCP, building a Claude integration, or troubleshooting FastMCP module-level server, storage, lifespan, middleware, OAuth, or deployment errors."
compatibility: claude-code-only

MCP Builder

Build a working MCP server from a description of the tools you need. Produces a deployable Python server using FastMCP.

Workflow

Step 1: Define What to Expose

Ask what the server needs to provide:

• **Tools** -- Functions Claude can call (API wrappers, calculations, file operations)
• **Resources** -- Data Claude can read (database records, config, documents)
• **Prompts** -- Reusable prompt templates with parameters

A brief like "MCP server for querying our customer database" is enough.

Step 2: Scaffold the Server

pip install fastmcp

Create the server file. The server instance MUST be at module level:

from fastmcp import FastMCP

# MUST be at module level for FastMCP Cloud
mcp = FastMCP("My Server")

@mcp.tool()
async def search_customers(query: str) -> str:
    """Search customers by name or email."""
    # Implementation here
    return f"Found customers matching: {query}"

@mcp.resource("customers://{customer_id}")
async def get_customer(customer_id: str) -> str:
    """Get customer details by ID."""
    return f"Customer {customer_id} details"

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

Step 3: Add Companion CLI Scripts (Optional)

For Claude Code terminal use, add scripts alongside the MCP server:

my-mcp-server/
├── src/index.ts          # MCP server (for Claude.ai)
├── scripts/
│   ├── search.ts         # CLI version of search tool
│   └── _shared.ts        # Shared auth/config
├── SCRIPTS.md            # Documents available scripts
└── package.json

CLI scripts provide file I/O, batch processing, and richer output that MCP can't. See `assets/SCRIPTS-TEMPLATE.md` and `assets/script-template.ts` for TypeScript templates.

Step 4: Test Locally

**Quick test -- run directly:**

python server.py

**Dev mode with inspector UI (recommended):**

fastmcp dev server.py
# Opens inspector at http://localhost:5173
# Hot reload, detailed logging, tool/resource inspection

**HTTP mode for remote clients:**

python server.py --transport http --port 8000

**Automated test script using FastMCP Client:**

import asyncio
from fastmcp import Client

async def test_server(server_path):
    async with Client(server_path) as client:
        # List everything
        tools = await client.list_tools()
        resources = await client.list_resources()
        prompts = await client.list_prompts()

        print(f"Tools: {[t.name for t in tools]}")
        print(f"Resources: {[r.uri for r in resources]}")
        print(f"Prompts: {[p.name for p in prompts]}")

        # Call first tool
        if tools:
            result = await client.call_tool(tools[0].name, {})
            print(f"Tool result: {result}")

        # Read first resource
        if resources:
            data = await client.read_resource(resources[0].uri)
            print(f"Resource data: {data}")

asyncio.run(test_server("server.py"))

Step 5: Pre-Deploy Checklist

Run these checks before deploying. All required checks must pass.

**Required (will cause deploy failure):**

1. Server file exists 2. Python syntax valid: `python3 -m py_compile server.py` 3. Module-level server object (not inside a function):

   grep -q "^mcp = FastMCP\|^server = FastMCP\|^app = FastMCP" server.py

4. `requirements.txt` exists with PyPI packages only (no `git+`, `-e`, `.whl`, `.tar.gz`) 5. No hardcoded secrets (check for `api_key = "..."` patterns excluding `os.getenv`/`os.environ`)

**Advisory (warnings):**

6. `fastmcp` listed in requirements.txt 7. `.gitignore` includes `.env` 8. No circular imports 9. Git repository initialised with remote 10. Server can load: `timeout 5 fastmcp inspect server.py`

Step 6: Deploy

**FastMCP Cloud (simplest):**

git add . && git commit -m "Ready for deployment"
git push -u origin main
# Visit https://fastmcp.cloud, connect repo, add env vars, deploy
# URL: https://your-project.fastmcp.app/mcp

Cloud requirements:

• Module-level server object named `mcp`, `server`, or `app`
• PyPI dependencies only in `requirements.txt`
• Public GitHub repository
• Environment variables for secrets (no hardcoded values)
• Auto-deploys on push to main, PR preview deployments

**Docker (self-hosted):**

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py", "--transport", "http", "--port", "8000"]

**Cloudflare Workers (edge):** Build it in TypeScript with Cloudflare's `agents` SDK (`McpAgent`); Cloudflare's remote MCP server docs carry the current template.

---

Critical Patterns

Module-Level Server Instance

FastMCP Cloud requires the server instance at module level:

# CORRECT
mcp = FastMCP("My Server")

@mcp.tool()
def my_tool(): ...

# WRONG -- Cloud can't find the server
def create_server():
    mcp = FastMCP("My Server")
    return mcp

# FIX for factory pattern -- export at module level
def create_server() -> FastMCP:
    mcp = FastMCP("server")
    return mcp
mcp = create_server()

Type Annotations Required

FastMCP uses type annotations to generate tool schemas:

@mcp.tool()
async def search(
    query: str,           # Required parameter
    limit: int = 10,      # Optional with default
    tags: list[str] = []  # Complex types supported
) -> str:
    """Docstring becomes the tool description."""
    ...

Error Handling

Return errors as strings, don't raise exceptions:

@m