fastmcp-bestpractices

FastMCP Best Practices for MCP Server Development

Overview

This rule provides comprehensive best practices for developing MCP servers using FastMCP 3.0, covering logging, tool design, error handling, testing, and production-ready patterns.

Core Principles

• FastMCP 3.0 First: Use the latest FastMCP features and patterns
• Pythonic Design: Write clean, maintainable Python code
• Production Ready: Build servers that work reliably in production
• Client Experience: Provide excellent user experience through proper logging and error handling
• Testing: Comprehensive testing for all functionality

Tool Development Best Practices

1. Tool Design Patterns

Simple Tools:

@mcp.tool
def add(a: int, b: int) -> int:
    """Add two numbers together."""
    return a + b

Async Tools with Context:

@mcp.tool
async def process_data(data: list[float], ctx: Context) -> dict:
    """Process numerical data with comprehensive logging."""
    await ctx.info(f"Processing {len(data)} data points")

    try:
        if not data:
            await ctx.warning("Empty data list provided")
            return {"error": "Empty data list"}

        result = sum(data) / len(data)
        await ctx.info(f"Processing complete, average: {result}")
        return {"average": result, "count": len(data)}

    except Exception as e:
        await ctx.error(f"Processing failed: {str(e)}")
        raise

2. Parameter Design

Use Type Annotations:

@mcp.tool
def validate_user(
    name: str,
    age: int,
    email: str,
    is_active: bool = True
) -> dict:
    """Validate user information."""
    # Tool logic here
    return {"valid": True, "user_id": "123"}

Complex Types:

from typing import List, Optional, Union
from pydantic import BaseModel

class UserData(BaseModel):
    name: str
    email: str
    preferences: List[str] = []

@mcp.tool
def create_user(user_data: UserData, ctx: Context) -> dict:
    """Create a new user with structured data."""
    await ctx.info(f"Creating user: {user_data.name}")
    # Implementation
    return {"user_id": "123", "status": "created"}