FastMCP: Pythonic way to create MCP servers and clients

Introduction

Model Context Protocol (MCP) has changed how large language models (LLMs) interact with external tools, data sources, and services. However, building an MCP server from scratch traditionally requires navigating complex boilerplate code and detailed protocol specifications. fastmcp Eliminates this barrier by providing a decorator-based, Pythonic framework that enables developers to create production-ready MCP servers and clients with minimal code.

This tutorial walks through creating an MCP server and client using FastMCP, complete with comprehensive error handling, making it suitable for both beginner and intermediate developers.

Prerequisites

This tutorial assumes the following are in place:

Python 3.10 or higher (3.11+ recommended for better async performance)
PIP or UV (UV is recommended for FastMCP deployments and required for CLI tools)
A code editor (any editor works; VS Code is a common choice)
Terminal/Command Line Information for Running Python Scripts

It is also beneficial to have a good knowledge of Python programming (functions, decorators, type hints), some understanding of async/await syntax (optional, but useful for advanced examples), familiarity with JSON and REST API concepts, and basic command-line terminal usage.

Before FastMCP, building an MCP server required a deep understanding of the MCP JSON-RPC specification, extensive boilerplate code for protocol handling, manual connection and transport management, and complex error handling and validation logic.

FastMCP addresses these issues with intuitive decorators and a simple, Pythonic API, enabling developers to focus on business logic rather than protocol implementation.

What Is the Model Context Protocol?

Model Context Protocol (MCP) is an open standard created by Anthropic. It provides a universal interface for AI applications to securely connect to external tools, data sources, and services. MCP standardizes how LLMs interact with external systems, just as Web APIs standardize web service communication.

Key Features of MCP

Standardized Communication: Uses JSON-RPC 2.0 for reliable, structured messaging
Bidirectional: Supports both requests and responses from client to server
Security: Built-in support for authentication and authorization patterns
Flexible Transportation: Works with any transport mechanism (stdio, HTTP, WebSocket, SSE)

MCP Architecture: Server and Client

MCP follows a clear client-server architecture:

MCP Server: Exposes capabilities (devices, resources, signals) that can be used by external applications. Think of it as a backend API designed specifically for LLM integration.
MCP Client: Embedded in AI applications (such as cloud desktops, cursor IDEs, or custom applications) that connect to MCP servers to access their resources.

Main components of MCP

MCP servers expose three primary types of capabilities:

tool: Executable functions that the LLM can call to perform actions. Tools can query databases, call APIs, perform calculations, or trigger workflows.
resources: Read-only data that MCP clients can obtain and use as reference. Resources can be file content, configuration data, or dynamically generated content.
Signal: Reusable message templates that guide LLM behavior. Signals provide coherent instructions for multi-step operations or special logic.

What is FastMCP?

FastMCP is a high-level Python framework that simplifies the process of building both MCP servers and clients. Designed to reduce development headaches, FastMCP has the following features:

Decorator-Based API: Python decorators (@mcp.tool, @mcp.resource, @mcp.prompt) remove the boilerplate
Security Type: Complete type hinting and validation using Python’s type system
Async/await support: Modern async Python for high-performance operations
Multiple Transportation: Support for stdio, HTTP, WebSocket and SSE
Built-in Test: Easy client-server testing without subprocess complexity
Production Ready: Features like error handling, logging, and configuration for production deployments

FastMCP philosophy

FastMCP relies on three main principles:

High level abstraction: Less code and faster development cycles
Easy: Minimal boilerplate allows focus on functionality over protocol details
Pythonic: Natural Python Idioms Make It Familiar to Python Developers

Installation

Start by installing FastMCP and the required dependencies. I recommend using uv.

If uv is not already installed, it can be added with pip:

Or install FastMCP directly with pip:

Verify that FastMCP is installed:

python -c "from fastmcp import FastMCP; print('FastMCP installed successfully')"

Creating a First MCP Server

The example builds a practical MCP server that exposes tools, resources, and prompts — a calculator server providing mathematical operations, configuration resources, and instruction prompts.

Step 1: Establishing the Project Structure

The first step is to create a project directory and initialize the environment. Create a folder for the project:

Then navigate into the project folder:

Start the project with the required files:

Step 2: Creating the MCP Server

Our Calculator MCP Server is a simple MCP server that displays tools, resources and hints. Inside the project folder, create a file named calculator_server.py And add the following code.

import logging
import sys
from typing import Dict
from fastmcp import FastMCP

# Configure logging to stderr (critical for MCP protocol integrity)
logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    stream=sys.stderr
)
logger = logging.getLogger(__name__)

# Create the FastMCP server instance
mcp = FastMCP(name="CalculatorServer")

Server imports FastMCP and configures logging stderr. The MCP protocol requires that all output except protocol messages be directed to stderr to prevent communication corruption. FastMCP(name="CalculatorServer") Creates a call server instance. It handles all protocol management automatically.

Now, let’s create our tools.

@mcp.tool
def add(a: float, b: float) -> float:
    """
    Add two numbers together.
   
    Args:
        a: First number
        b: Second number
       
    Returns:
        Sum of a and b
    """
    try:
        result = a + b
        logger.info(f"Addition performed: {a} + {b} = {result}")
        return result
    except TypeError as e:
        logger.error(f"Type error in add: {e}")
        raise ValueError(f"Invalid input types: {e}")

@mcp.tool
def subtract(a: float, b: float) -> float:
    """
    Subtract b from a.
   
    Args:
        a: First number (minuend)
        b: Second number (subtrahend)
       
    Returns:
        Difference of a and b
    """
    try:
        result = a - b
        logger.info(f"Subtraction performed: {a} - {b} = {result}")
        return result
    except TypeError as e:
        logger.error(f"Type error in subtract: {e}")
        raise ValueError(f"Invalid input types: {e}")

The server defines functions for addition and subtraction. Both are wrapped in a try-catch block to raise value errors, log information, and return results.

@mcp.tool
def multiply(a: float, b: float) -> float:
    """
    Multiply two numbers.
   
    Args:
        a: First number
        b: Second number
       
    Returns:
        Product of a and b
    """
    try:
        result = a * b
        logger.info(f"Multiplication performed: {a} * {b} = {result}")
        return result
    except TypeError as e:
        logger.error(f"Type error in multiply: {e}")
        raise ValueError(f"Invalid input types: {e}")

@mcp.tool
def divide(a: float, b: float) -> float:
    """
    Divide a by b.
   
    Args:
        a: Dividend (numerator)
        b: Divisor (denominator)
       
    Returns:
        Quotient of a divided by b
       
    Raises:
        ValueError: If attempting to divide by zero
    """
    try:
        if b == 0:
            logger.warning(f"Division by zero attempted: {a} / {b}")
            raise ValueError("Cannot divide by zero")
       
        result = a / b
        logger.info(f"Division performed: {a} / {b} = {result}")
        return result
    except (TypeError, ZeroDivisionError) as e:
        logger.error(f"Error in divide: {e}")
        raise ValueError(f"Division error: {e}")

Four decorated ceremonies (@mcp.tool) highlight mathematical operations. Each device includes:

Type prompts for parameters and return values
Extensive docstrings (MCP uses these as tool descriptions)
Error handling try-except blocks
Logging for debugging and monitoring
input validation

Let’s move on to building resources.

@mcp.resource("config://calculator/settings")
def get_settings() -> Dict:
    """
    Provides calculator configuration and available operations.
   
    Returns:
        Dictionary containing calculator settings and metadata
    """
    logger.debug("Fetching calculator settings")
   
    return {
        "version": "1.0.0",
        "operations": ("add", "subtract", "multiply", "divide"),
        "precision": "IEEE 754 double precision",
        "max_value": 1.7976931348623157e+308,
        "min_value": -1.7976931348623157e+308,
        "supports_negative": True,
        "supports_decimals": True
    }

@mcp.resource("docs://calculator/guide")
def get_guide() -> str:
    """
    Provides a user guide for the calculator server.
   
    Returns:
        String containing usage guide and examples
    """
    logger.debug("Retrieving calculator guide")

    guide = """
       
    1. **add(a, b)**: Returns a + b
       Example: add(5, 3) = 8
   
    2. **subtract(a, b)**: Returns a - b
       Example: subtract(10, 4) = 6
   
    3. **multiply(a, b)**: Returns a * b
       Example: multiply(7, 6) = 42
   
    4. **divide(a, b)**: Returns a / b
       Example: divide(20, 4) = 5.0
   
    ## Error Handling
   
    - Division by zero will raise a ValueError
    - Non-numeric inputs will raise a ValueError
    - All inputs should be valid numbers (int or float)
   
    ## Precision
   
    The calculator uses IEEE 754 double precision floating-point arithmetic.
    Results may contain minor rounding errors for some operations.
    """
   
    return guide

Two decorated ceremonies (@mcp.resource) Provide static and dynamic data:

config://calculator/settings: Returns metadata about the calculator
docs://calculator/guide: Returns a formatted user guide
URI format distinguishes resource types (convention: type://category/resource)

Let’s create our signs.

@mcp.prompt
def calculate_expression(expression: str) -> str:
    """
    Provides instructions for evaluating a mathematical expression.
    Args:
        expression: A mathematical expression to evaluate        
    Returns:
        Formatted prompt instructing the LLM how to evaluate the expression
    """
    logger.debug(f"Generating calculation prompt for: {expression}")

    prompt = f"""
    Please evaluate the following mathematical expression step by step:
   
    Expression: {expression}
   
    Instructions:
    1. Break down the expression into individual operations
    2. Use the appropriate calculator tool for each operation
    3. Follow order of operations (parentheses, multiplication/division, addition/subtraction)
    4. Show all intermediate steps
    5. Provide the final result
   
    Available tools: add, subtract, multiply, divide
    """
   
    return prompt.strip()

Finally, add the server startup script.

if __name__ == "__main__":
    logger.info("Starting Calculator MCP Server...")
   
    try:
        # Run the server with stdio transport (default for Claude Desktop)
        mcp.run(transport="stdio")
    except KeyboardInterrupt:
        logger.info("Server interrupted by user")
        sys.exit(0)
    except Exception as e:
        logger.error(f"Fatal error: {e}", exc_info=True)
        sys.exit(1)

@mcp.prompt The decorator creates instruction templates that guide LLM behavior for complex tasks.

Best practices for error handling include:

Catching specific exceptions (TypeError, ZeroDivisionError)
Meaningful error messages for users
Detailed logging for debugging
graceful error propagation

Step 3: Building the MCP Client

This step demonstrates how to interact with the calculator MCP server created above. Create a new file named calculator_client.py.

import asyncio
import logging
import sys
from typing import Any
from fastmcp import Client, FastMCP

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    stream=sys.stderr
)
logger = logging.getLogger(__name__)

async def main():
    """
    Main client function demonstrating server interaction.
    """
   
    from calculator_server import mcp as server
   
    logger.info("Initializing Calculator Client...")

    try:
        async with Client(server) as client:
            logger.info("✓ Connected to Calculator Server")
           
            # DISCOVER CAPABILITIEs            
            print("n" + "="*60)
            print("1. DISCOVERING SERVER CAPABILITIES")
            print("="*60)
           
            # List available tools
            tools = await client.list_tools()
            print(f"nAvailable Tools ({len(tools)}):")
            for tool in tools:
                print(f"  • {tool.name}: {tool.description}")
           
            # List available resources
            resources = await client.list_resources()
            print(f"nAvailable Resources ({len(resources)}):")
            for resource in resources:
                print(f"  • {resource.uri}: {resource.name or resource.uri}")
           
            # List available prompts
            prompts = await client.list_prompts()
            print(f"nAvailable Prompts ({len(prompts)}):")
            for prompt in prompts:
                print(f"  • {prompt.name}: {prompt.description}")
           
            # CALL TOOLS
           
            print("n" + "="*60)
            print("2. CALLING TOOLS")
            print("="*60)
           
            # Simple addition
            print("nTest 1: Adding 15 + 27")
            result = await client.call_tool("add", {"a": 15, "b": 27})
            result_value = extract_tool_result(result)
            print(f"  Result: 15 + 27 = {result_value}")
           
            # Division with error handling
            print("nTest 2: Dividing 100 / 5")
            result = await client.call_tool("divide", {"a": 100, "b": 5})
            result_value = extract_tool_result(result)
            print(f"  Result: 100 / 5 = {result_value}")
           
            # Error case: division by zero
            print("nTest 3: Division by Zero (Error Handling)")
            try:
                result = await client.call_tool("divide", {"a": 10, "b": 0})
                print(f"  Unexpected success: {result}")
            except Exception as e:
                print(f"  ✓ Error caught correctly: {str(e)}")
           
            # READ RESOURCES
            print("n" + "="*60)
            print("3. READING RESOURCES")
            print("="*60)
           
            # Read settings resource
            print("nFetching Calculator Settings...")
            settings_resource = await client.read_resource("config://calculator/settings")
            print(f"  Version: {settings_resource(0).text}")
           
            # Read guide resource
            print("nFetching Calculator Guide...")
            guide_resource = await client.read_resource("docs://calculator/guide")
            # Print first 200 characters of guide
            guide_text = guide_resource(0).text(:200) + "..."
            print(f"  {guide_text}")
           
            # CHAINING OPERATIONS
           
            print("n" + "="*60)
            print("4. CHAINING MULTIPLE OPERATIONS")
            print("="*60)
           
            # Calculate: (10 + 5) * 3 - 7
            print("nCalculating: (10 + 5) * 3 - 7")
           
            # Step 1: Add
            print("  Step 1: Add 10 + 5")
            add_result = await client.call_tool("add", {"a": 10, "b": 5})
            step1 = extract_tool_result(add_result)
            print(f"    Result: {step1}")
           
            # Step 2: Multiply
            print("  Step 2: Multiply 15 * 3")
            mult_result = await client.call_tool("multiply", {"a": step1, "b": 3})
            step2 = extract_tool_result(mult_result)
            print(f"    Result: {step2}")
           
            # Step 3: Subtract
            print("  Step 3: Subtract 45 - 7")
            final_result = await client.call_tool("subtract", {"a": step2, "b": 7})
            final = extract_tool_result(final_result)
            print(f"    Final Result: {final}")
           
            # GET PROMPT TEMPLATE
           
            print("n" + "="*60)
            print("5. USING PROMPT TEMPLATES")
            print("="*60)
           
            expression = "25 * 4 + 10 / 2"
            print(f"nPrompt Template for: {expression}")
            prompt_response = await client.get_prompt(
                "calculate_expression",
                {"expression": expression}
            )
            print(f"  Template:n{prompt_response.messages(0).content.text}")
           
            logger.info("✓ Client operations completed successfully")
   
    except Exception as e:
        logger.error(f"Client error: {e}", exc_info=True)
        sys.exit(1)

From the above code, the client uses async with Client(server) For secure connection management. It automatically handles connection setup and cleanup.

A helper function is also needed to handle the results.

def extract_tool_result(response: Any) -> Any:
    """
    Extract the actual result value from a tool response.
   
    MCP wraps results in content objects, this helper unwraps them.
    """
    try:
        if hasattr(response, 'content') and response.content:
            content = response.content(0)
            # Prefer explicit text content when available (TextContent)
            if hasattr(content, 'text') and content.text is not None:
                # If the text is JSON, try to parse and extract a `result` field
                import json as _json
                text_val = content.text
                try:
                    parsed_text = _json.loads(text_val)
                    # If JSON contains a result field, return it
                    if isinstance(parsed_text, dict) and 'result' in parsed_text:
                        return parsed_text.get('result')
                    return parsed_text
                except _json.JSONDecodeError:
                    # Try to convert plain text to number
                    try:
                        if '.' in text_val:
                            return float(text_val)
                        return int(text_val)
                    except Exception:
                        return text_val

            # Try to extract JSON result via model `.json()` or dict-like `.json`
            if hasattr(content, 'json'):
                try:
                    if callable(content.json):
                        json_str = content.json()
                        import json as _json
                        try:
                            parsed = _json.loads(json_str)
                        except _json.JSONDecodeError:
                            return json_str
                    else:
                        parsed = content.json

                    # If parsed is a dict, try common shapes
                    if isinstance(parsed, dict):
                        # If nested result exists
                        if 'result' in parsed:
                            res = parsed.get('result')
                        elif 'text' in parsed:
                            res = parsed.get('text')
                        else:
                            res = parsed

                        # If res is str that looks like a number, convert
                        if isinstance(res, str):
                            try:
                                if '.' in res:
                                    return float(res)
                                return int(res)
                            except Exception:
                                return res
                        return res

                    return parsed
                except Exception:
                    pass
        return response
    except Exception as e:
        logger.warning(f"Could not extract result: {e}")
        return response


if __name__ == "__main__":
    logger.info("Calculator Client Starting...")
    asyncio.run(main())

Looking at the above code, before using the tool, the client lists the available capabilities. await client.list_tools() Gets all tool metadata including descriptions. await client.list_resources() Searches for available resources. At the end, await client.list_prompts() Will find templates available soon.

await client.call_tool() The method does the following:

Takes tool name and parameters as dictionary
Returns a wrapped response object containing the result.
Integrates with error handling for tool failures

After getting the results, extract_tool_result() The helper function opens the MCP’s response format to get the actual value, handling both JSON and text responses.

The chaining operation shown above demonstrates how to use the output from one tool as input to another, enabling complex calculations across multiple tool calls.

Finally, the error handling tool catches errors (like division by zero) and logs them gracefully without crashing.

Step 4: Running the Server and Client

Two terminals are needed. In the first terminal, start the server:

python calculator_server.py

The server should print:

Run the client on terminal 2:

python calculator_client.py

The output will show:

Advanced Patterns with FastMCP

While the calculator example uses basic logic, FastMCP is designed to handle complex, production-ready scenarios. As an MCP server scales, it can take advantage of:

Asynchronous Operation: Use async def For tools that perform I/O-bound tasks such as database queries or API calls
Dynamic Resources: Can accept resource arguments (e.g., resource://users/{user_id}) to quickly fetch specific data points
Complex type of verification: Use Pydantic models or complex Python type prompts to ensure that LLM sends data in the exact format required by the backend.
Custom Transportation: in this walkthrough stdioFastMCP also supports SSE (Server-Sent Events) for web-based integration and custom UI tools

Limitations and What to Watch

FastMCP removes much of the boilerplate around the Model Context Protocol, but a few caveats are worth keeping in mind. It is a higher-level abstraction over the protocol, so the convenience comes at the cost of some control; unusual transport, authentication or performance requirements can still require dropping down to the underlying MCP specification. The calculator example here is deliberately simple — production servers must also address authentication, rate limiting, input validation, observability and safe error propagation, none of which a small demo exercises. MCP and its Python tooling are evolving quickly, so decorator names, transports and CLI behavior can change between versions; the FastMCP documentation and the official Model Context Protocol specification are the authoritative references when behavior differs from a tutorial. Because MCP servers can expose real tools and data to a language model, careful scoping of permissions and validation of model-driven actions remain essential. Readers building typed, reliable agents on top of these servers may also find this walkthrough of reliable agent workflows with PydanticAI useful.

Conclusion

FastMCP bridges the gap between the complex Model Context Protocol and the clean, decorator-based developer experience expected by Python programmers. By removing the boilerplate associated with JSON-RPC 2.0 and manual transport management, it allows developers to focus on what matters: Creating tools that make LLM more efficient.

This tutorial covered:

Main structure of MCP (server vs client)
how to define tool For tasks, resources for data, and signals for instructions
How to build a functional client to test and exercise the server logic

Whether the goal is a simple utility or a complex data-orchestration layer, FastMCP provides the most “Pythonic” path to a production-ready agentic ecosystem.