ajafry/fastmcp-streamable-middleware

Remote MCP Server (Streamable HTTP) utilizing Middleware

A demonstration project showcasing how to build and integrate a Model Context Protocol (MCP) server using FastMCP with FastAPI. This project implements a mathematical operations server that exposes tools for addition, subtraction, and multiplication through the MCP protocol.

🚀 Features

• MCP Server Implementation: Built with FastMCP for seamless LLM tool integration
• FastAPI Integration: Mounts the MCP server within a FastAPI application
• Streamable HTTP Protocol: Uses efficient streamable HTTP transport for client-server communication
• Custom Middleware: Demonstrates middleware implementation for request logging and tool management
• Mathematical Tools: Exposes three mathematical operations (add, subtract, multiply) as MCP tools
• Health Monitoring: Includes health check endpoints for monitoring server status

🏗️ Architecture

Server Components

1. FastMCP Server (server.py):

   • Initializes a FastMCP server with mathematical tools
   • Implements custom middleware for logging and tool management
   • Uses streamable HTTP protocol for efficient communication
   • Mounts within FastAPI for unified deployment

2. Custom Middleware (shared/simple_fastmcp_middleware.py):

   • Logs incoming requests and tool invocations
   • Provides visibility into tool availability and usage
   • Demonstrates middleware lifecycle hooks

3. MCP Client (client.py):

   • Connects to the MCP server using StreamableHttpTransport
   • Lists available tools from the server
   • Demonstrates basic client-server interaction

📋 Prerequisites

• Python 3.8+
• FastMCP library
• FastAPI framework

🛠️ Installation

1. Clone the repository:

git clone <repository-url>
cd fast-mcp

2. Install dependencies:

pip install -r requirements.txt

🚀 Usage

Starting the Server

Run the MCP server with uvicorn:

uvicorn server:app --reload --port 8000

The server will start on http://localhost:8000 with the following endpoints:

• Health Check: GET /health
• MCP Protocol: /simple-mcp/mcp/* (mounted MCP server)

Running the Client

In a separate terminal, run the client to test the connection:

python client.py

This will connect to the server and list all available tools.

🔧 Key Implementation Details

Mounting MCP Server in FastAPI

The project demonstrates how to mount a FastMCP server within a FastAPI application:

# Initialize FastMCP server
mcp = FastMCP("Math Operations Server")
mcp.add_middleware(SimpleMiddleware())

# Create FastAPI app and mount MCP server
mcp_app = mcp.http_app(transport="streamable-http")
app = FastAPI(lifespan=mcp_app.lifespan)
app.mount("/simple-mcp", mcp_app)

Streamable HTTP Transport

The project uses streamable HTTP protocol for efficient client-server communication:

# Server side
mcp_app = mcp.http_app(transport="streamable-http")

# Client side
client = Client(StreamableHttpTransport("http://localhost:8000/simple-mcp/mcp"))

Custom Middleware Implementation

The SimpleMiddleware class demonstrates how to implement custom middleware for:

• Request logging and monitoring
• Tool availability tracking
• Tool invocation logging

class SimpleMiddleware(Middleware):
    async def on_request(self, context: MiddlewareContext, call_next):
        self.log_info(f"*** on_request inside MCP server")
        return await call_next(context)

    async def on_call_tool(self, context: MiddlewareContext, call_next):
        # Log tool invocations
        return await call_next(context)

Tool Definition

Mathematical tools are defined using FastMCP decorators:

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

🧪 Available Tools

The server exposes three mathematical tools:

1. add(a, b): Adds two numbers
2. subtract(a, b): Subtracts second number from first
3. multiply(a, b): Multiplies two numbers

🔍 API Endpoints

• GET /health - Health check endpoint
• POST /simple-mcp/mcp/tools/list - List available MCP tools
• POST /simple-mcp/mcp/tools/call - Invoke MCP tools
• GET /simple-mcp/mcp/protocol - MCP protocol information

🏁 Benefits of This Architecture

1. Unified Deployment: Both REST APIs and MCP tools under one server
2. Efficient Communication: Streamable HTTP protocol reduces overhead
3. Middleware Support: Custom logging, authentication, and monitoring
4. Scalability: FastAPI's performance with MCP's protocol efficiency
5. Development Experience: Hot reloading and comprehensive logging

🤝 Contributing

Feel free to submit issues, feature requests, or pull requests to improve this demonstration project.

📄 License

This project is provided as a demonstration and learning resource.