Creating MCP Servers

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

Core Capabilities

1. Apply mandatory patterns - Four critical 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)

Trigger Patterns

Activate this skill when:

• "MCP server", "create MCP", "build MCP", "FastMCP"
• "progressive disclosure", "gateway pattern", "context efficient"
• "optimize MCP", "reduce context", "tool descriptions"
• "MCPB", "bundle MCP", "package server"

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)

Four critical requirements for ALL implementations:

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/MANDATORYPATTERNS.md](references/MANDATORYPATTERNS.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 LLMSTXT.md for "authentication" → webfetch 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/PROGRESSIVEDISCLOSURE.md](references/PROGRESSIVEDISCLOSURE.md)

Implementation Phases

Phase 1: Research

Read LLMSTXT.md → Find relevant URLs → webfetch documentation

Phase 2: Implement

Load appropriate reference based on architecture decision. Apply all four mandatory patterns.

Phase 3: Package (Optional)

cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

See [references/MCPBBUNDLING.md](references/MCPBBUNDLING.md) for manifest format.

Reference Library

Documentation index (load first for FastMCP knowledge):

• [LLMSTXT.md](references/LLMSTXT.md) - Complete FastMCP v2 documentation URLs

Core patterns:

• [MANDATORYPATTERNS.md](references/MANDATORYPATTERNS.md) - Four critical requirements
• [PROGRESSIVEDISCLOSURE.md](references/PROGRESSIVEDISCLOSURE.md) - Architecture for 5+ capabilities

Implementation:

• [GATEWAYPATTERNS.md](references/GATEWAYPATTERNS.md) - Three production-ready implementations
• [MCPBBUNDLING.md](references/MCPBBUNDLING.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 ❌ websearch for FastMCP docs (use webfetch 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