FastMCP Integration Application Demo
This project demonstrates a modular application built with FastMCP, integrating an MCP server, a FastAPI interface, and LLM Agent capabilities.
Project Architecture
The project utilizes a modular design, separating different functionalities into distinct packages:
app/
├── __init__.py
├── api/ # FastAPI Application Layer
│ ├── __init__.py
│ ├── main.py # FastAPI main application entry point
│ └── routers/ # API route definitions
│ ├── __init__.py
│ ├── agent.py # Agent mode routes
│ ├── mcp_resources.py # MCP resource routes
│ └── mcp_tools.py # MCP tool routes
├── llm/ # LLM (Large Language Model) Processing Layer
│ ├── __init__.py
│ ├── base.py # Base LLM class
│ └── openai.py # OpenAI implementation
└── mcp_server/ # MCP Server Definition Layer
├── __init__.py
├── base.py # Base MCP Server class
├── run.py # Script for internal Client connection or direct execution
└── simple.py # Simple MCP Server implementation (with tools & resources)
main.py # Main entry point (runs API or MCP server)
Core Workflow (API Mode):
- Run MCP Server Independently: Start a separate MCP server process using
python main.py --mode mcp, listening on a specified port (default: 8001) with SSE transport. - Run API Server: Start the FastAPI server using
python main.py --mode api(listens on 8080). - Connection: The
mcp_clientwithin the FastAPI server connects to the independently running MCP server via SSE. - Request Handling: Frontend or other clients interact with the application through the HTTP API provided by FastAPI.
- Tool/Resource/Agent Calls: FastAPI routes forward requests to the
mcp_client(communicating with the MCP server) or thellmmodule (communicating with the LLM API).
Features
- Modular Design: Clear separation of concerns (API, LLM, MCP) for easy extension and maintenance.
- Dual Run Modes:
apimode: Runs the FastAPI server, requires a separately running MCP server.mcpmode: Runs the MCP server directly for testing or connection by other clients.
- LLM Integration: Supports using OpenAI (or other extensible LLMs) to process tool outputs or execute in Agent mode.
- Agent Mode: Provides an
/api/agent/processendpoint for the LLM to autonomously select and call MCP tools. - Complete API: Offers RESTful endpoints for MCP tools, resources, and Agent functionality via FastAPI.
- Persistent Connection: The API server maintains a long-lived SSE connection to the MCP server for efficiency.
Installation
-
Clone the repository (if needed).
-
Install dependencies (using uv or pip):
# Recommended: use uv uv pip install -e . # Alternatively, use pip # pip install -e .
-
Set Environment Variables:
- The
OPENAI_API_KEYenvironment variable is required to use LLM features. - You can create a
.envfile in the project root and define it there:OPENAI_API_KEY=sk-...
- The
Usage
Running the API Server (Recommended)
This mode requires first starting the standalone MCP server.
-
Start the MCP Server (in one terminal):
# Uses SSE transport, listening on 127.0.0.1:8001 (default) python main.py --mode mcp # Or specify a different host and port # python main.py --mode mcp --mcp-host 0.0.0.0 --mcp-port 8002
-
Start the API Server (in another terminal):
# Listens on 0.0.0.0:8080 (default) python main.py --mode api # Use a different port or enable hot-reloading (for development) # python main.py --mode api --port 9000 --reload
The API server is now accessible at
http://localhost:8080(or your specified port). It will automatically connect to the MCP server started in step 1 (default connection:http://localhost:8001/sse).
Running the MCP Server Directly
If you only need to run the MCP server (e.g., for direct connection by other FastMCP clients):
# Default: Use SSE transport, listening on 127.0.0.1:8001
python main.py --mode mcp
# Use Standard I/O (stdio) transport
# python main.py --mode mcp --mcp-transport stdio
API Endpoints (Accessed via API Server)
The API server runs on http://localhost:8080 (default).
- MCP Tools (
/api/tools):GET /: List all available tools and their parameters.POST /{tool_name}: Call a specific tool. Example request body:{"params": {"a": 5, "b": 3}, "use_llm": true, "system_message": "Explain the result"}
- MCP Resources (
/api/resources):GET /: List all available resource URIs and their types.GET /{resource_path:path}: Get the content of a specific resource (e.g.,GET /api/resources/example/greeting).
- Agent Mode (
/api/agent):POST /process: Let the LLM autonomously handle a user request, potentially calling tools. Example request body:{"prompt": "What is 5 plus 3?"}
- Health Checks:
GET /health: Check if the API server is running.GET /api/tools/health: Check the connection status between the API server and the MCP server.
Extending the Application
Adding New Tools
- Extend
BaseMCPServerinapp/mcp_server/simple.py(or create a new server file). - Define new tools using the
@self.mcp.tool()decorator within the_register_toolsmethod. - If you created a new server file, import and instantiate it in
app/mcp_server/run.py.
Adding New LLM Providers
- Create a new Python file in the
app/llm/directory (e.g.,anthropic.py). - Create a new class inheriting from
app.llm.base.BaseLLM. - Implement the
generateandgenerate_with_toolsmethods. - Import and use the new LLM class where needed (e.g., in
agent.py).
Development
Enable hot-reloading when running the API server for development:
# Ensure the standalone MCP server is still running
python main.py --mode api --reload
Metadata
Release files for iflow-mcp_zhouhaojiang-fastapi-with-fatmcp-agent 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0.tar.gz | 17.0 kB | Without provenance | Details for iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0-py3-none-any.whl |
Total release size: 36.9 kB
Release files / iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0.tar.gz
| Download URL | iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0.tar.gz |
|---|---|
| Size | 17.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b15a1b6c14b4f1538081c54f8f5d058d7b87ccbf184424731fa56ed1a80954f
|
|
BLAKE2b-256 checksum How to use checksums |
d6f8138615a3e901c6f6e0e7941c33929ee2357a00a83f5582f7ee42bcc6d43c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_zhouhaojiang_fastapi_with_fatmcp_agent-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e0f8cf0ea7d022dafac239642b8db67304ad27ab77e26b9973186d466a56b33f
|
|
BLAKE2b-256 checksum How to use checksums |
9d2a4af8aa1f60d8407bf89b4f9df6aa4c5ec9dd921d9cbbc7bf8faf17b63cee
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_zhouhaojiang-fastapi-with-fatmcp-agent 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.