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:

Reference Documentation (reference/) - 6 comprehensive guides covering all aspects of FastMCP development
Code Examples (examples/) - Runnable examples from minimal to complete servers
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

User asks about OpenAI integration:

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

User asks about AWS Cognito authentication:

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

User asks about testing patterns:

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

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:

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)
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
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:

Choose resource types:
- Static resources (status, features, documentation)
- Dynamic resources (generated content)
- Template resources (with path parameters)
- Wildcard resources (multi-segment paths)
Create resources in app/resources/:
- static.py for static resources
- Separate files for dynamic/template/wildcard
Example resource:

# app/resources/welcome.py

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

**Ste

fastmcp-builder