FastAPI MCP SSE Utility

English | 简体中文

A robust implementation of Server-Sent Events (SSE) leveraging the FastAPI framework, augmented with Model Context Protocol (MCP) interoperability.

Understanding MCP

The Model Context Protocol (MCP) establishes an open standard facilitating interaction between sophisticated AI models and external instruments or data repositories. MCP addresses critical bottlenecks in advanced AI deployment:

• Information Currency: Overcomes inherent training data staleness by granting models access to current facts.
• Utility Bridging: Standardizes the mechanism through which models invoke external APIs and software modules.
• Platform Neutrality: Ensures a consistent communication layer across disparate AI frameworks and toolsets.
• Adaptability: Simplifies the augmentation of AI system capabilities without necessitating model retraining.

This repository serves as a functional template for deploying MCP using SSE within a FastAPI environment.

Overview

This project details the construction of Server-Sent Events (SSE) streaming utilizing FastAPI, coupled with integrated Model Context Protocol (MCP) capabilities. The central utility lies in the seamless embedding of MCP's SSE requirements inside a fully operational FastAPI web service that supports custom URL mappings.

Key Capabilities

• Native Server-Sent Events (SSE) support enhanced with MCP logic.
• Deep integration within the FastAPI application structure, allowing for custom path definitions.
• A cohesive web service hosting both standard HTTP endpoints and dedicated MCP communication channels.
• Highly configurable URL structure.
• Clear architectural partitioning between web application logic and MCP transport mechanisms.

System Blueprint

This structure emphasizes modularity, demonstrating how to:

1. Incorporate MCP's SSE conduits (/sse and /messages/) into the primary FastAPI application instance.
2. Reserve traditional web paths (/, /about, /status, /docs, /redoc).
3. Enforce a clean separation between the core web presentation layer and the MCP streaming logic.

Setup & Execution Procedures

Requirements Check

Install UV Package Manager - A high-performance Python dependency manager built in Rust:

cmd powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Execution Path A: Immediate Run (No Local Clone)

Execute the application directly via UV's remote invocation utility:

cmd uvx --from git+https://github.com/panz2018/fastapi_mcp_sse.git start

Execution Path B: Complete Local Setup

1. Environment Isolation

Establish an isolated Python execution context:

cmd uv venv

2. Context Activation

Bring the isolated environment online:

cmd .venv\Scripts\activate

3. Dependency Resolution

Fetch all requisite packages listed in the manifest file:

cmd uv pip install -r pyproject.toml

4. Launch the Consolidated Server

Start the FastAPI instance featuring the integrated MCP SSE capability:

cmd python src/server.py

Alternatively:

cmd uv run start

Accessible Network Locations

Once the service is operational (using either Method A or B), the following interfaces are reachable (assuming default port 8000):

• Primary Server Interface: http://localhost:8000
• Standard Web Interface Paths:
• Landing Page: http://localhost:8000/
• Information Page: http://localhost:8000/about
• Health Check API: http://localhost:8000/status
• API Specifications (Swagger): http://localhost:8000/docs
• Alternative API Specs (ReDoc): http://localhost:8000/redoc
• MCP Streaming Paths:
• SSE Stream Endpoint: http://localhost:8000/sse
• Data Submission Point: http://localhost:8000/messages/

Diagnostics with MCP Inspector

For rigorous verification and debugging of MCP interactions, utilize the dedicated MCP Inspector tool:

cmd mcp dev ./src/weather.py

Linking to MCP Inspector

1. Access the MCP Inspector UI at http://localhost:5173.
2. Configure the connection parameters:
3. Set Transport Mechanism to SSE.
4. Input the URL: http://localhost:8000/sse.
5. Activate the link via the Connect button.

Validating Tool Functionality

1. Navigate to the 'Tools' interface within the Inspector.
2. Execute List Tools to enumerate available capabilities:
3. get_alerts : Retrieves meteorological warnings.
4. get_forcast : Fetches anticipated weather conditions.
5. Select the desired operational function.
6. Input all mandatory arguments.
7. Initiate the execution process by clicking Run Tool.

Extending the Service Framework

Introducing Custom Web Routes

The architecture promotes straightforward extension via FastAPI's APIRouter class:

1. In the routes.py file, define new request handlers using the router instance:

python @router.get("/new-route") async def new_route(): return {"message": "This is a new route"}

1. All paths defined via this router object are automatically merged into the main application context.

Modifying MCP Streaming Configuration

The core MCP SSE connection logic is managed within server.py via:

• Instantiating the necessary SSE communication transport.
• Establishing the dedicated SSE handling routine.
• Registering the MCP-specific routes onto the FastAPI application object.

Configuration for Continue

To leverage this MCP data source seamlessly with the Continue VS Code extension, update your Continue settings JSON as follows:

{ "experimental": { "modelContextProtocolServers": [ { "transport": { "name": "weather", "type": "sse", "url": "http://localhost:8000/sse" } } ] } }

Related Technology: XMLHttpRequest (XHR)

XMLHttpRequest (XHR) is a crucial browser API implemented as a JavaScript object. Its methods enable a web application to dispatch HTTP queries to a backend server subsequent to initial page load, facilitating the retrieval of data asynchronously. XHR is fundamental to Asynchronous JavaScript and XML (Ajax) programming paradigms. Before Ajax, server interaction primarily relied on standard hyperlink navigation or HTML form submissions, actions that typically mandated a complete page refresh.

== Development Chronology == The conceptual basis for XMLHttpRequest originated in the year 2000, developed by the engineering team behind Microsoft Outlook. This concept was subsequently brought to fruition within Internet Explorer version 5 (released in 1999). Notably, the initial implementation did not utilize the standardized XMLHttpRequest identifier; rather, it employed COM identifiers like ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). By the release of Internet Explorer 7 (2006), browser support universally adopted the canonical XMLHttpRequest designation.

The XMLHttpRequest identifier has since become the established convention across major browser engines, including Mozilla's Gecko (starting 2002), Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Process === The World Wide Web Consortium (W3C) published the initial Working Draft specification for the XMLHttpRequest object on April 5, 2006. A subsequent Working Draft, Level 2, arrived on February 25, 2008. Level 2 introduced capabilities for monitoring request progress, enabling cross-origin requests, and managing byte-level data streams. By the close of 2011, the Level 2 features were integrated back into the main specification document. As of late 2012, stewardship for the specification shifted to the WHATWG, which maintains a continuous document using the Web IDL description language.

== Operational Steps == Executing a network query using XMLHttpRequest generally involves a sequence of distinct programming actions.

1. Instantiation: Create an instance of the XMLHttpRequest object via its constructor.
2. Configuration (open): Invoke the open method to define the HTTP method (e.g., GET, POST), specify the target resource Uniform Resource Identifier (URI), and elect for synchronous or asynchronous execution flow.
3. Event Handling (Async): For asynchronous operations, assign a callback function to monitor state transitions of the request.
4. Transmission (send): Trigger the request submission by calling the send method, optionally including payload data.
5. Response Processing: Monitor the state changes within the listener. Upon successful completion, the server's response body is typically accessible via the responseText property when the state reaches 4 (the 'done' state). Beyond these foundational steps, XHR offers fine-grained control over transmission parameters and response handling. Custom request headers can be set to guide server behavior, and data can be uploaded dynamically within the send call. Furthermore, the received data can be parsed directly from JSON into native JavaScript objects or processed incrementally as chunks arrive, avoiding blocking waits for the entire transmission. The request pipeline can be terminated prematurely or configured with a timeout limit to prevent indefinite waiting.