fastmcp-builder

FastMCP Builder - Production MCP Server Development

Overview

This skill provides comprehensive, production-ready patterns for building MCP (Model Context Protocol) servers using FastMCP, the official high-level Python framework. It includes complete reference implementations, working examples, and best practices proven in production.

FastMCP is the recommended approach for building MCP servers in Python - it's simpler, faster to develop, and more maintainable than the low-level MCP SDK.

What's Included

This skill contains:

1. Reference Documentation (reference/) - 6 comprehensive guides covering all aspects of FastMCP development
2. Code Examples (examples/) - Runnable examples from minimal to complete servers
3. Complete Reference Project (reference-project/) - Full production implementation with:
   • 6 production-ready tools
   • 7 resource instances (4 types)
   • 1 universal prompt
   • 145 passing tests
   • OAuth integration
   • Complete documentation

💡 Tip: When in doubt, look at the reference-project for real-world implementation examples.

When to Use This Skill

Use this skill when you need to:

✅ Build MCP servers with FastMCP - Python-based MCP server development ✅ Add OAuth authentication - Especially Google OAuth for remote access ✅ Implement production patterns - Tools, resources, prompts with best practices ✅ Set up comprehensive testing - Using FastMCP Client for fast, in-memory tests ✅ Structure larger projects - Proper organization and separation of concerns ✅ Deploy to production - With authentication, error handling, monitoring

Don't use this skill for:

• ❌ TypeScript/Node.js MCP servers (use mcp-builder skill instead)
• ❌ Low-level MCP protocol work (use MCP SDK directly)
• ❌ Non-FastMCP Python servers (this is FastMCP-specific)

Consulting Official Documentation

IMPORTANT: When encountering questions or issues not covered in this skill's reference materials, you should:

Primary Method: Use WebSearch (Recommended)

The most reliable way to find FastMCP documentation is using WebSearch with site-specific queries:

WebSearch(
    query="site:gofastmcp.com [your specific topic]"
)

This will search the official FastMCP documentation site and return relevant pages.

Alternative: Direct Page Access

If you know the general documentation structure, you can fetch specific pages directly:

WebFetch(
    url="https://gofastmcp.com/[section]/[topic]",
    prompt="Your specific question about this topic"
)

Common documentation sections:

• /getting-started/ - Installation, quickstart, welcome
• /servers/ - Tools, resources, prompts, context, logging
• /deployment/ - Running servers, HTTP deployment, configuration
• /integrations/ - Auth0, AWS Cognito, Azure, GitHub, Google, WorkOS, OpenAI, etc.
• /testing/ - Testing guides and best practices

Tip: Any page can be accessed as markdown by appending .md to the URL.

When to Consult Official Docs

Consult official documentation when:

• You encounter a feature or API not covered in this skill's references
• You need the latest updates or breaking changes
• User asks about FastMCP capabilities you're unsure about
• You're implementing advanced patterns not in the reference materials
• There are version-specific behaviors or deprecations
• You need clarification on authentication providers beyond Google OAuth
• You want to verify current best practices

Example Workflows

1. User asks about OpenAI integration:

   WebSearch(query="site:gofastmcp.com openai integration")
   → Find https://gofastmcp.com/integrations/openai
   → Fetch that page for details
   

2. User asks about AWS Cognito authentication:

   WebSearch(query="site:gofastmcp.com aws cognito oauth")
   → Find relevant auth documentation
   → Implement based on official guidance
   

3. User asks about testing patterns:

   WebSearch(query="site:gofastmcp.com testing")
   → Find testing documentation
   → Apply patterns from official docs
   

4. Exploring what's available:

   WebSearch(query="site:gofastmcp.com deployment options")
   WebSearch(query="site:gofastmcp.com authentication providers")
   → Browse results to see available topics
   

Note: Always try the reference materials in this skill first, then consult official docs if needed.

---

Workflow - Building a FastMCP Server

Phase 1: Planning & Setup

Step 1.1: Review FastMCP Overview

• Load fastmcp_overview.md
• Understand FastMCP vs MCP SDK
• Confirm FastMCP is right choice (it usually is)

Step 1.2: Understand Requirements

• What tools does the server need?
• Do you need OAuth authentication?
• Will you have resources? Prompts?
• What's the deployment target?

Step 1.3: Review Project Structure

• Load project_structure.md
• Understand the recommended directory layout
• Learn about the common.py pattern (DRY principle)
• Understand dual-mode pattern (with/without OAuth)

Step 1.4: Set Up Project

Create project structure:

mkdir my-mcp-server
cd my-mcp-server

# Create directories
mkdir -p app/tools app/resources app/prompts tests

# Create initial files
touch app/__init__.py
touch app/main.py
touch app/main_noauth.py
touch app/common.py
touch app/config.py
touch tests/__init__.py
touch pyproject.toml
touch .env.example
touch README.md

Initialize with uv:

# Install FastMCP
uv add fastmcp==2.13.0.1
uv add python-dotenv==1.2.1

# Add test dependencies
uv add --optional test pytest==8.4.2 pytest-asyncio==1.2.0 pytest-mock==3.15.1 httpx==0.28.1

---

Phase 2: Core Implementation

Step 2.1: Implement Configuration

Create app/config.py based on patterns in project_structure.md:

• Environment variable loading
• Configuration class with validation
• OAuth settings (if needed)
• Server metadata

Step 2.2: Implement Tools

Load tool_patterns.md for comprehensive patterns:

1. Identify tool patterns needed:

   • Basic sync tools (health checks, simple queries)
   • Data processing tools (analysis, transformation)
   • Tools with Context (logging, progress)
   • Stateful tools (if state management needed)
   • API integration tools (external services)

2. Create tools in app/tools/:

   • One file per tool or logical group
   • Follow patterns from tool_patterns.md
   • Use proper error handling
   • Add comprehensive docstrings

3. Example tool structure:

# app/tools/my_tool.py

async def my_tool(param: str, ctx: Context | None = None) -> dict:
    """
    Tool description

    Args:
        param: Parameter description
        ctx: FastMCP context (auto-injected)

    Returns:
        dict: Result structure
    """
    try:
        if ctx:
            await ctx.info("Processing...")

        # Tool logic here
        result = process(param)

        if ctx:
            await ctx.info("Completed!")

        return {"status": "success", "data": result}

    except Exception as e:
        if ctx:
            await ctx.error(f"Failed: {e}")
        return {"status": "error", "error": str(e)}

Step 2.3: Implement Resources (if needed)

Load resource_patterns.md for all resource types:

1. Choose resource types:

   • Static resources (status, features, documentation)
   • Dynamic resources (generated content)
   • Template resources (with path parameters)
   • Wildcard resources (multi-segment paths)

2. Create resources in app/resources/:

   • static.py for static resources
   • Separate files for dynamic/template/wildcard

3. Example resource:

# app/resources/welcome.py

def get_welcome_message() -> str:
    """Welcome message resource"""
    return "Welcome to my MCP server!"

Step 2.4: Implement Prompts (if needed)

Create reusable prompt templates:

# app/prompts/explain.py

def explain_concept(
    concept: str,
    audience_level: str = "intermediate",
) -> str:
    """Generate explanation prompt"""
    return f"Explain {concept} for {audience_level} audience..."

Step 2.5: Create Common Registration

In app/common.py, register all components:

from fastmcp import FastMCP

# Import tools
from app.tools.my_tool import my_tool

# Import resources
from app.resources.welcome import get_welcome_message

# Import prompts
from app.prompts.explain import explain_concept


def register_all(mcp: FastMCP) -> None:
    """Register all components - DRY principle"""

    # Tools
    mcp.tool()(my_tool)

    # Resources
    mcp.resource("greeting://welcome")(get_welcome_message)

    # Prompts
    mcp.prompt()(explain_concept)

Step 2.6: Create Server Entry Points

app/main_noauth.py (for local development):

from fastmcp import FastMCP
from app.config import Config
from app.common import register_all

mcp = FastMCP(Config.SERVER_NAME)
register_all(mcp)

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

app/main.py (with OAuth - if needed): Load oauth_integration.md for complete OAuth setup.

---

Phase 3: OAuth Integration (if needed)

Only if you need remote access with authentication.

Step 3.1: Set Up Google OAuth

Follow oauth_integration.md:

1. Create OAuth Client in Google Cloud Console
2. Configure environment variables (.env)
3. Implement GoogleProvider in main.py
4. Set up ngrok for testing
5. Configure Claude Desktop Connectors

Step 3.2: Test OAuth Flow

1. Start ngrok
2. Start server with base-url
3. Connect Claude Desktop
4. Verify authentication works

---

Phase 4: Testing

Step 4.1: Set Up Test Structure

Load testing_guide.md for comprehensive testing patterns.

Create tests/conftest.py:

import pytest
from fastmcp import Client
from app.main_noauth import mcp


@pytest.fixture
async def client():
    """Provide FastMCP client for testing"""
    async with Client(mcp) as c:
        yield c

Step 4.2: Write Tool Tests

# tests/test_tools.py

@pytest.mark.asyncio
async def test_my_tool(client):
    """Should execute my_tool successfully"""
    result = await client.call_tool("my_tool", {"param": "test"})
    assert result.data["status"] == "success"

Step 4.3: Write Resource Tests

# tests/test_resources.py

@pytest.mark.asyncio
async def test_welcome_resource(client):
    """Should read welcome resource"""
    content = await client.read_resource("greeting://welcome")
    assert "Welcome" in content

Step 4.4: Write Integration Tests

# tests/test_integration.py

@pytest.mark.asyncio
async def test_complete_workflow(client):
    """Should execute complete workflow"""
    # Test multiple components working together
    pass

Step 4.5: Run Tests

# Run all tests
uv run pytest tests/ -v

# Run with coverage
uv run pytest tests/ --cov=app --cov-report=html

---

Phase 5: Documentation & Deployment

Step 5.1: Write README

Document:

• Project description
• Features
• Quick start guide
• OAuth setup (if applicable)
• Usage examples
• Testing instructions
• Deployment guide

Step 5.2: Prepare for Deployment

1. Environment Variables:

   • Create .env.example template
   • Document all required variables
   • Never commit .env to git

2. Testing:

   • Ensure all tests pass
   • Test OAuth flow (if applicable)
   • Test in production-like environment

3. Deployment:

   • Choose platform (Railway, Fly.io, VPS)
   • Set up HTTPS (required for OAuth)
   • Configure environment variables
   • Deploy and test

---

Reference Documentation

Load these as needed during development:

Core References

• fastmcp_overview.md - FastMCP introduction, when to use, key features
• project_structure.md - Recommended structure, file organization, patterns

Implementation Guides

• tool_patterns.md - 6 tool patterns with complete examples
• resource_patterns.md - 4 resource types (static, dynamic, template, wildcard)
• oauth_integration.md - Complete Google OAuth setup guide
• testing_guide.md - FastMCP Client testing, patterns, best practices

Example Code

Run or reference these complete examples:

• minimal_server.py - Absolute simplest FastMCP server
• complete_server_structure.py - Full-featured single-file example
• test_examples.py - Comprehensive testing examples

---

Quick Start Examples

Example 1: Minimal Server

from fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def greet(name: str) -> str:
    """Greet someone"""
    return f"Hello, {name}!"

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

Example 2: Server with Multiple Components

from fastmcp import FastMCP, Context

mcp = FastMCP("my-server")

# Tool
@mcp.tool()
async def process(text: str, ctx: Context | None = None) -> dict:
    if ctx:
        await ctx.info("Processing...")
    return {"result": text.upper()}

# Resource
@mcp.resource("greeting://hello")
def get_greeting() -> str:
    return "Hello from resource!"

# Prompt
@mcp.prompt()
def explain(topic: str) -> str:
    return f"Explain {topic} in detail"

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

Example 3: With OAuth

from fastmcp import FastMCP
from fastmcp.server.auth.providers.google import GoogleProvider
import os

auth = GoogleProvider(
    client_id=os.getenv("GOOGLE_CLIENT_ID"),
    client_secret=os.getenv("GOOGLE_CLIENT_SECRET"),
    base_url="https://your-server.com",
)

mcp = FastMCP("my-server", auth=auth)

# ... add tools, resources, prompts ...

if __name__ == "__main__":
    mcp.run(transport="http", host="0.0.0.0", port=8000)

---

Best Practices Summary

1. ✅ Use FastMCP - Simpler than MCP SDK for most use cases
2. ✅ Follow project structure - Use common.py pattern (DRY)
3. ✅ Dual-mode servers - main.py (OAuth) + main_noauth.py (local)
4. ✅ Comprehensive testing - Use FastMCP Client, aim for >80% coverage
5. ✅ Clear documentation - Docstrings, README, usage examples
6. ✅ Error handling - Graceful failures, informative error messages
7. ✅ Context usage - Logging, progress for better UX
8. ✅ Security - Environment variables, never commit secrets

---

Common Workflows

Creating a New Tool

1. Create app/tools/my_tool.py
2. Implement tool function
3. Add to app/common.py registration
4. Write tests in tests/test_tools.py
5. Run tests: uv run pytest tests/test_tools.py -v

Adding OAuth

1. Review oauth_integration.md
2. Set up Google OAuth credentials
3. Update app/config.py with OAuth settings
4. Modify app/main.py to use GoogleProvider
5. Test with ngrok
6. Configure Claude Desktop Connectors

Debugging

1. Use main_noauth.py for faster local testing
2. Add logging with Context: await ctx.debug(...)
3. Write tests to isolate issues
4. Check tool/resource registration in common.py
5. Verify environment variables loaded

---

Additional Resources

• FastMCP Documentation: https://gofastmcp.com/
• FastMCP GitHub: https://github.com/jlowin/fastmcp
• MCP Specification: https://modelcontextprotocol.io/
• Google OAuth Guide: https://developers.google.com/identity/protocols/oauth2

---

Notes

• This skill focuses on FastMCP, not the low-level MCP SDK
• All examples use Python 3.11+
• OAuth examples use Google OAuth (other providers possible)
• Testing uses FastMCP Client (in-memory, fast)
• Deployment examples are production-ready

Happy building! 🚀