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)

When to Use

Trigger phrases:

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

Use for:

• Creating new MCP servers with FastMCP v2
• Optimizing existing tool descriptions
• Implementing progressive disclosure for 5+ capabilities
• Converting Skills to MCP or vice versa
• Packaging servers for distribution

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/FASTMCP_DOCS.md for relevant URLs
  → Use web_fetch on gofastmcp.com URLs

Mandatory Patterns

Four critical requirements for ALL implementations:

1. uv (never pip) - Dependency management consistency
2. Optimized tool descriptions - Annotations, Annotated, concise docstrings
3. Authoritative documentation - Fetch from gofastmcp.com (see workflow below)
4. Strategic tool selection - Best tool for each job

Details in references/MANDATORY_PATTERNS.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

Implementation Workflow

Phase 1: Research FastMCP Patterns

IMPORTANT: Claude fetches documentation, not scripts (skill environment has restricted network access).

Workflow:

1. Read references/FASTMCP_DOCS.md - comprehensive URL index
2. Identify relevant documentation URLs for your task
3. Use web_fetch on gofastmcp.com URLs (Claude has network access)
4. Apply patterns from fetched documentation

Example searches:

• Authentication patterns → Search FASTMCP_DOCS.md for "authentication"
• Tool optimization → Search for "tools"
• OAuth flows → Search for "oauth"
• Deployment → Search for "deployment"

URL format: All docs at https://gofastmcp.com/[path].md

Phase 2: Implement Server

Load appropriate reference based on architecture decision above.

For standard servers:

• Apply all four mandatory patterns
• Optimize tool descriptions (annotations, Annotated, Field)
• Single-sentence docstrings with high information density

For gateway servers:

• Implement three-tier loading (discover, load, execute)
• Use proven patterns from GATEWAY_PATTERNS.md
• Validate 85%+ context reduction

Phase 3: Package (Optional)

Simple zip bundling:

# 1. Create manifest.json (see MCPB_BUNDLING.md for format)
# 2. Bundle with zip
cd /home/claude
zip -r server-name.mcpb manifest.json server.py README.md
cp server-name.mcpb /mnt/user-data/outputs/

# Or for automated builds:
python scripts/create_mcpb.py server.py --name server-name --version 1.0.0

See references/MCPB_BUNDLING.md for manifest format and details.

Reference Library

Load as needed during development:

Documentation index:

• FASTMCP_DOCS.md - Complete FastMCP v2 documentation URLs (Claude fetches via web_fetch)

Core patterns (load first):

• MANDATORY_PATTERNS.md - Four critical requirements
• PROGRESSIVE_DISCLOSURE.md - Architecture for 5+ capabilities

Implementation:

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

Scripts (execute as needed):

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

Network Access Note

Skill environment: Restricted network (package repos only)
Claude (using skill): Full network access via web_fetch

This means:

• Scripts cannot fetch URLs
• Claude must use web_fetch for gofastmcp.com documentation
• FASTMCP_DOCS.md provides URL index for Claude to fetch

Verification Checklist

Before completing any FastMCP implementation:

✓ Uses uv (not pip)
✓ FastMCP docs fetched from gofastmcp.com (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)
✓ Strategic tool usage documented

For gateway implementations, additionally verify:

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

Key Optimization

Tool description pattern:

Before (180 tokens):

Search for items in the database.
This tool allows comprehensive searching...

After (55 tokens):

"""Search items. Fast full-text search."""
# + annotations={"title": "Search", "readOnlyHint": True}
# + Annotated parameters with Field

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 gofastmcp.com)
❌ Verbose tool descriptions
❌ Missing tool annotations
❌ Gateway for 1-3 tools (overhead exceeds benefit)
❌ Mixing unrelated capabilities in single gateway
❌ Scripts trying to fetch URLs (network restricted)

Expected Results

Context efficiency:

• 85-93% baseline reduction (gateway pattern)
• 65-70% tool description reduction (optimization)
• 0 tokens for script execution (progressive disclosure)

Quality:

• Production-ready immediately
• All mandatory patterns applied
• Security and error handling included
• Strategic tool usage documented