creating-mcp-servers

Creating MCP Servers

Build production-ready MCP servers using FastMCP v2 with optimal context efficiency through progressive disclosure patterns.

Core Capabilities

1. Apply the core patterns - Four requirements for consistency
2. Implement progressive disclosure - Gateway patterns achieving 85-93% token reduction
3. Optimize tool descriptions - 65-70% token reduction through proper patterns
4. Bundle servers - Package as MCPB files with validation
5. Proven gateway patterns - Three complete implementations (Skills, API, Query)

Architecture Decision

1-3 simple tools?
  → Standard FastMCP with optimized tools
  Load: references/MANDATORY_PATTERNS.md

5+ related capabilities? → Gateway pattern (progressive disclosure) Load: references/PROGRESSIVE_DISCLOSURE.md Load: references/GATEWAY_PATTERNS.md

Optimize existing server? → Apply mandatory patterns Load: references/MANDATORY_PATTERNS.md

Package for distribution? → MCPB bundler Load: references/MCPB_BUNDLING.md Execute: scripts/create_mcpb.py

Need FastMCP documentation? → Search references/LLMS_TXT.md for relevant URLs → Use web_fetch on gofastmcp.com URLs

## Mandatory Patterns (Summary)

Every implementation should meet these four requirements:

1. **uv (never pip)** - `uv pip install fastmcp`
2. **Optimized tool descriptions** - Annotations, Annotated, concise docstrings
3. **Authoritative documentation** - Fetch from gofastmcp.com via LLMS_TXT.md index
4. **Apply all patterns** - Every implementation meets verification checklist

Details in [references/MANDATORY_PATTERNS.md](references/MANDATORY_PATTERNS.md)

## Documentation Retrieval Workflow

**To fetch FastMCP documentation:**

1. Read references/LLMS_TXT.md - complete URL index
2. Search for relevant topic keywords
3. Use web_fetch on matched URLs (append .md for markdown)
4. Apply patterns from fetched documentation

**Example:** Authentication patterns → Search LLMS_TXT.md for "authentication" → web_fetch https://gofastmcp.com/servers/auth/authentication.md

## Progressive Disclosure Pattern

For servers with 5+ capabilities:

**Three-tier loading:**
1. Metadata (~20 tokens/capability) - Always loaded
2. Content (~500 tokens) - Load on demand
3. Execution (0 tokens) - Execute without loading

Achieves 85-93% baseline reduction. See [references/PROGRESSIVE_DISCLOSURE.md](references/PROGRESSIVE_DISCLOSURE.md)

## Implementation Phases

### Phase 1: Research
Read LLMS_TXT.md → Find relevant URLs → web_fetch documentation

### Phase 2: Implement
Load appropriate reference based on architecture decision. Apply all four patterns.

### Phase 3: Package (Optional)
```bash
cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

See references/MCPB_BUNDLING.md for manifest format.

Reference Library

Documentation index (load first for FastMCP knowledge):

• LLMS_TXT.md - Complete FastMCP v2 documentation URLs

Core patterns:

• MANDATORY_PATTERNS.md - the four core requirements
• PROGRESSIVE_DISCLOSURE.md - Architecture for 5+ capabilities

Implementation:

• GATEWAY_PATTERNS.md - Three production-ready implementations
• MCPB_BUNDLING.md - Packaging and distribution

Scripts:

• scripts/create_mcpb.py - Bundle MCP servers into .mcpb files

Verification Checklist

Before completing any FastMCP implementation:

✓ Uses uv (not pip)
✓ FastMCP docs fetched from LLMS_TXT.md URLs (not web_search)
✓ Tool annotations (readOnlyHint, title, openWorldHint)
✓ Annotated parameters with Field
✓ Single-sentence docstrings
✓ 65-70% token reduction vs verbose
✓ Server instructions concise (<100 chars)

For gateway implementations, additionally verify:

✓ 85%+ baseline context reduction
✓ Discover returns metadata only
✓ Load fetches content on demand
✓ Execute runs without context cost

Tool Description Pattern

Before (180 tokens):

@mcp.tool()
async def search_items(query: str):
    """Search for items in the database.
    This tool allows comprehensive searching..."""

After (55 tokens):

@mcp.tool(
    annotations={"title": "Search", "readOnlyHint": True, "openWorldHint": False}
)
async def search_items(
    query: Annotated[str, Field(description="Search text")],
    ctx: Context = None
):
    """Search items. Fast full-text search across all fields."""

Common Pitfalls

❌ Using mcpb pack CLI (causes crashes, just use zip)
❌ Using pip instead of uv
❌ web_search for FastMCP docs (use web_fetch on LLMS_TXT.md URLs)
❌ Verbose tool descriptions
❌ Missing tool annotations
❌ Gateway for 1-3 tools (overhead exceeds benefit)
❌ Mixing unrelated capabilities in single gateway