FastAPI with Model Context Protocol (MCP)

A FastAPI application integrated with Model Context Protocol (MCP) for mathematical operations and tool registration examples. This project demonstrates how to build MCP servers using FastAPI and shows different approaches to registering tools.

Features

• FastAPI web framework integration with MCP
• Multiple mathematical operations (add, multiply, subtract)
• Different tool registration patterns (decorators vs functions)
• Server-Sent Events (SSE) support for real-time communication
• Example configurations for MCP client integration
• Pandas integration for data manipulation demonstrations

Project Structure

fastapi-with-mcp/
├── fastapi_mcp.py          # Main FastAPI + MCP application
├── test_tool_registration.py # Tool registration testing examples
├── config.json             # MCP client configuration
├── pyproject.toml          # Python project configuration
├── .python-version         # Python version specification
├── .gitignore              # Git ignore rules
├── uv.lock                 # UV lock file for dependencies
└── README.md               # This file

Requirements

• Python 3.12+
• FastAPI[standard]
• FastMCP
• Pandas
• Pydantic
• MCP

Installation

1. Clone the repository:

git clone <repository-url>
cd fastapi-with-mcp

2. Create a virtual environment (using uv or standard Python):

# Using uv (recommended)
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Or using standard Python
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

# Using uv
uv pip install -e .

# Or using pip
pip install -e .

Usage

Running the FastAPI + MCP Server

Start the main application:

uvicorn fastapi_mcp:app --reload --port 8000

The server will be available at:

• FastAPI docs: http://localhost:8000/docs
• MCP SSE endpoint: http://localhost:8000/mcp-server/sse
• MCP server mount: http://localhost:8000/mcp-server

Available Tools

The application provides several mathematical tools that demonstrate Pandas integration:

1. Add - Add two numbers using pandas DataFrame operations
2. Multiply - Multiply two numbers using pandas DataFrame operations
3. Subtract - Subtract two numbers using pandas DataFrame operations

Each operation creates a pandas DataFrame to perform the calculation, demonstrating how to integrate data manipulation libraries with MCP tools.

Tool Registration Methods

This project demonstrates multiple ways to register MCP tools:

Method 1: Decorator Approach

@mcp.tool
@app.get("/add", operation_id="add_two_numbers")
async def add(a: int, b: int):
    """Add two numbers and return the sum."""
    summ = pd.DataFrame({"a": [a], "b": [b], "sum": [a + b]})
    result = int(summ.loc[0, "sum"])
    return {"sum": result}

Method 2: Function Registration

def multiply(a: int, b: int):
    """Multiply two numbers and return the product."""
    product = pd.DataFrame({"a": [a], "b": [b], "product": [a * b]})
    result = int(product.loc[0, "product"])
    return {"product": result}

# Register the function as a tool
mcp.tool(multiply)

Method 3: Decorator as Function

def subtract(a: int, b: int):
    """Subtract two numbers and return the difference."""
    diff = pd.DataFrame({"a": [a], "b": [b], "difference": [a - b]})
    result = int(diff.loc[0, "difference"])
    return {"difference": result}

# Register using the decorator syntax as a function
mcp.tool()(subtract)

Method 4: Combined FastAPI + MCP

@app.get("/multiply", operation_id="multiply_two_numbers")
async def multiply_endpoint(a: int, b: int):
    """FastAPI endpoint that also works as MCP tool."""
    return multiply(a, b)

# Register the same function as an MCP tool
mcp.tool(multiply_endpoint)

MCP Client Configuration

The config.json file contains example configuration for MCP clients:

{
  "mcpServers": {
    "math-tools": {
      "type": "http",
      "url": "http://localhost:8000/mcp-server/sse",
      "env": {}
    }
  }
}

This configuration:

• Uses "math-tools" as the server identifier (reflecting the mathematical operations provided)
• Sets type to "http" for HTTP-based communication
• Points to the mounted MCP server endpoint at "/mcp-server/sse"

API Endpoints

FastAPI Endpoints

• GET /add?a={int}&b={int} - Add two numbers
• GET /multiply?a={int}&b={int} - Multiply two numbers
• GET /docs - Interactive API documentation
• GET /redoc - ReDoc API documentation

MCP Endpoints

• GET /mcp-server/sse - Server-Sent Events endpoint for MCP communication
• MCP tools are accessible through the MCP protocol via the mounted server at /mcp-server

Development

Testing Tool Registration

Run the tool registration test to see different registration methods:

python test_tool_registration.py

Simple MCP Server Example

For testing tool registration methods, see test_tool_registration.py:

python test_tool_registration.py

Dependencies

• FastAPI[standard]: Modern, fast web framework for building APIs with standard extras
• FastMCP: FastAPI integration for Model Context Protocol
• Pandas: Data manipulation library (used for mathematical operations)
• Pydantic: Data validation library
• MCP: Model Context Protocol implementation

Environment Variables

This project uses dotenv to load environment variables. Create a .env file for environment-specific configurations:

# Add any environment variables here if needed
# Example:
# DEBUG=true
# LOG_LEVEL=info

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Learn More

• FastAPI Documentation
• Model Context Protocol
• FastMCP Documentation

Troubleshooting

Common Issues

1. Module name conflicts: Avoid naming files mcp.py as it conflicts with the MCP package
2. Port conflicts: Ensure port 8000 is available or change the port in uvicorn command
3. Python version: This project requires Python 3.12+
4. Dependencies: Make sure all dependencies are installed with the correct versions

Getting Help

If you encounter issues:

1. Check the FastAPI docs at /docs endpoint
2. Verify all dependencies are installed correctly
3. Ensure Python 3.12+ is being used
4. Check server logs for detailed error messages
5. Verify that the MCP SSE endpoint is accessible at /mcp-server/sse