FastAPI MCP Client

FastAPI MCP Client

A specialized client library specifically designed to work with fastapi-mcp servers that implement the Model Context Protocol (MCP) over Server-Sent Events (SSE). This library provides a seamless way to interact with MCP-enabled FastAPI services.

Installation

# Install with pip
pip install fastapi-mcp-client

# Or with UV
uv add fastapi-mcp-client

Quick Start

import asyncio
from fastapi_mcp_client import MCPClient

async def main():
    async with MCPClient("http://localhost:8000") as client:
        # Call a non-streaming operation
        result = await client.call_operation("echo", {"message": "Hello, MCP!"})
        print(f"Echo result: {result}")
        
        # Call a streaming operation with SSE
        stream = await client.call_operation(
            "generate_numbers", 
            {"count": 5},
            stream=True
        )
        
        async for event in stream:
            print(f"Event: {event}")

asyncio.run(main())

Features

• MCP Protocol Support: Full implementation of the Model Context Protocol
• SSE Streaming: First-class support for Server-Sent Events (SSE) streaming
• Async-First Design: Fully async-compatible for high-performance applications
• Seamless Session Management: Handles MCP session establishment and message passing
• Error Handling: Comprehensive error handling with fallback mechanisms
• Type Annotations: Full type hints for better IDE integration and validation

Running Examples

The repository includes examples to help you get started. Here's how to run them:

1. Clone the Repository

git clone https://github.com/RooseveltAdvisors/fastapi-mcp-client.git
cd fastapi-mcp-client

2. Set Up Environment

# Create and activate virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install all dependencies including examples
uv sync --all-extras

3. Start the Example Server

# In one terminal
cd examples/server
python simpler_server.py

This starts a FastAPI server with several MCP-enabled endpoints:

• echo: Returns the message you send
• generate_numbers: Streams a sequence of numbers
• search_documents: Simulates a document search with streaming results
• calculate: Evaluates a simple math expression

4. Run the SSE Client Example

# In another terminal (with virtual env activated)
cd examples
python sse_example.py

Advanced Usage

Custom Client Configuration

from fastapi_mcp_client import MCPClient, MCPClientConfig

config = MCPClientConfig(
    base_url="http://localhost:8000",
    timeout=60.0,
    log_level="DEBUG"
)

async with MCPClient("http://localhost:8000", config=config) as client:
    # Call a streaming tool with custom configuration
    stream = await client.call_operation(
        "generate_numbers", 
        {"count": 10},
        stream=True
    )
    
    async for event in stream:
        print(f"Received event: {event}")

Understanding the MCP/SSE Flow

sequenceDiagram
    participant C as Client
    participant S as Server

    Note over C,S: Establish SSE Connection
    C->>+S: GET /mcp (Accept: text/event-stream)
    S-->>-C: 200 OK (Connection Open)
    S-->>C: SSE: data: /mcp/messages/?session_id=XXX

    Note over C: Parse session_id=XXX

    Note over C,S: MCP Initialization
    C->>+S: POST /mcp/messages/?session_id=XXX <br> Payload: {method: "initialize", ...}
    S-->>-C: 202 Accepted

    Note over C,S: MCP Tool Call
    C->>+S: POST /mcp/messages/?session_id=XXX <br> Payload: {method: "tools/call", ...}
    S-->>-C: 202 Accepted

    Note over C,S: Stream Results
    S-->>C: SSE: data: {result_part_1}
    S-->>C: SSE: data: {result_part_2}
    S-->>C: SSE: data: {final_result}
    Note over S: (Closes SSE Connection or sends close event)

Examples

Check out the examples directory for more:

• Server Example: A sample FastAPI MCP server
• SSE Example: Advanced streaming with custom configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

1. Clone the repository

   git clone https://github.com/RooseveltAdvisors/fastapi-mcp-client.git
   cd fastapi-mcp-client
   

2. Install uv

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Create and activate a virtual environment

   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

4. Install development dependencies

   uv sync --all-extras
   

5. Run tests

   pytest
   

Pull Request Process

1. Create your feature branch (git checkout -b feature/amazing-feature)
2. Make your changes and ensure tests pass
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.

Acknowledgments

• Built to work with FastAPI MCP - a FastAPI extension for adding MCP support to your APIs