FastAPI MCP Server + LangChain Client Example

FastAPI MCP 服务 + LangChain 客户端示例

本示例项目演示如何使用 fastapi-mcp 将 FastAPI 端点公开为模型上下文协议（MCP）工具。还包含一个基础的 LangChain Agent（langchain_client.py），它使用 langchain-mcp-adapters 通过 HTTP/SSE 连接到本地 FastAPI 服务，以发现和使用已公开的工具。

先决条件

开始之前，请确保已安装以下内容：

• Python： 建议使用 3.10 或更高版本。
• uv： 本项目使用的 Python 包管理器。（安装说明）
• Node.js 和 npm： npx 所需（用于运行可选的 MCP Inspector）。你可以从 nodejs.org 下载 Node.js（其中包含 npm）。
• Git： 用于克隆仓库。
• OpenAI API 密钥： LangChain 客户端示例所需。你需要在 .env 文件中设置此密钥。

本项目演示如何设置基础的 FastAPI 应用，并使用 fastapi-mcp 库将其端点公开为模型上下文协议（MCP）工具。项目还包含一个 LangChain Agent 客户端，用于连接并使用这些工具，并介绍如何配置 Cursor 进行连接。

开始使用 / 如何运行

1. 克隆仓库：

   git clone <your-repo-url>
   cd <repo-directory>
   

2. 安装 uv： 如果尚未安装，请安装 uv 包管理器（命令见下文的项目设置）。

3. 设置环境并安装依赖项：

   uv init # If pyproject.toml doesn't exist
   uv venv # Create virtual environment (.venv)
   # Install all project dependencies
   uv pip install fastapi "uvicorn[standard]" fastapi-mcp langchain-mcp-adapters langgraph langchain-openai python-dotenv
   

4. 创建 .env 文件： 在项目根目录中创建名为 .env 的文件，并添加你的 OpenAI API 密钥：

   OPENAI_API_KEY=your_openai_api_key_here
   

5. 运行 FastAPI MCP 服务： 打开终端并运行：

   uvicorn main:app --reload --port 8000
   

   保持此终端处于运行状态。 (或者，你可以在 VS Code / Cursor 中使用 .vscode/launch.json 里定义的 Python: FastAPI MCP 调试配置，在附加调试器的情况下运行服务。)

6. 运行 LangChain 客户端： 打开_第二个_终端并运行：

   uv run python langchain_client.py
   

   客户端将连接到服务、发现工具，并使用 Agent 运行查询。

7. （可选）使用 MCP Inspector 测试服务： 运行 LangChain 客户端之前，或者进行更直接的测试时，可以使用官方 MCP Inspector 工具：

   • 确保 FastAPI 服务正在运行（步骤 5）。
   • 打开另一个终端并运行：npx @modelcontextprotocol/inspector （npx 随 Node.js/npm 一同提供。如果此命令失败，请确保已安装 Node.js，并且可通过 PATH 访问。）
   • 在 Inspector 界面中，连接到你的服务 URL：http://127.0.0.1:8000/mcp
   • 转到“Tools”，点击“List Tools”以查看 read_root__get 和 greet_user_greet__name__get。
   • 选择一个工具，填写参数（例如，greet_user 的 name），然后点击“Run Tool”。

8. （可选）使用 LangChain 客户端测试 greet_user： greet_user 端点及 langchain_client.py 中对应的测试查询（query2）目前处于启用状态。只需运行 LangChain 客户端（步骤 6），并观察执行的第二部分；此处应会尝试向用户 'LangChain' 问好。

   • （如果想禁用此测试，请注释掉 main.py 中的 @app.get("/greet/{name}") 端点，以及 langchain_client.py 中的 query2 部分。）

目标

构建一个具备 MCP 能力的简单 FastAPI 服务，用于学习和测试，可在本地运行，并可连接到 Cursor 编辑器中的 Agent 等 MCP 客户端。

项目设置

1. 包管理器： 我们使用了 uv，这是一个用 Rust 编写、速度很快的 Python 包安装和解析工具。
   • 安装（Windows PowerShell）：irm https://astral.sh/uv/install.ps1 | iex
   • 初始化项目：uv init（创建 pyproject.toml）
   • 虚拟环境：uv venv（创建并管理 .venv）
2. 依赖项： 使用 uv 安装：

   # 开发期间使用的具体命令（已包含在“开始使用”部分的合并安装命令中）：
   # uv pip install fastapi "uvicorn[standard]" fastapi-mcp
   # uv pip install langchain-mcp-adapters langgraph langchain-openai python-dotenv
   

   这会将 FastAPI、Uvicorn ASGI 服务、fastapi-mcp、LangChain 组件和 python-dotenv 安装到 .venv 虚拟环境中。

应用（main.py）

创建了一个包含以下端点的简单 FastAPI 应用：

• /：返回欢迎消息。
• /greet/{name}：返回个性化问候语（目前已注释掉）。

重要的是，fastapi-mcp 集成是在 FastAPI 路由定义之后完成的：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI(...)

# --- Define FastAPI routes (@app.get, @app.post, etc.) ---
@app.get("/")
async def read_root():
    # ... endpoint logic ...

# --- Initialize and mount fastapi-mcp AFTER routes ---
mcp = FastApiMCP(app)
mcp.mount() # Exposes tools under /mcp by default

运行服务

• 直接运行： uvicorn main:app --reload --port 8000
• 使用调试器（Cursor/VS Code）： 在 .vscode 中创建了 launch.json 文件，以便在调试器附加的情况下运行应用。

LangChain 客户端（langchain_client.py）

• 从 .env 文件读取 OPENAI_API_KEY。
• 使用 langchain-mcp-adapters（MultiServerMCPClient）通过 SSE 连接到运行中的 FastAPI 服务 http://127.0.0.1:8000/mcp。
• 自动发现 MCP 服务公开的工具。
• 使用发现的工具和 OpenAI LLM 创建 LangGraph ReAct Agent。
• 通过 Agent 运行示例查询。

Cursor 集成（MCP 客户端）

1. 配置： 在项目根目录中创建了 .cursor/mcp.json 文件：

   {
     "mcpServers": {
       "local-fastapi-mcp": {
         "url": "http://127.0.0.1:8000/mcp"
       }
     }
   }
   

2. 启用： 需要在 Cursor 设置中启用服务（按 Ctrl+，搜索“Cursor Settings”，然后转到“MCP”选项卡）。
3. 使用： 随后可以在聊天面板中要求 Cursor Agent 使用发现的工具。

重要经验

• uv 基础用法： uv init、uv venv 和 uv pip install 可快速设置 Python 项目环境。
• fastapi-mcp 初始化顺序： 必须在定义 FastAPI 路由（如 @app.get）之后创建 FastApiMCP(app) 实例并调用 mcp.mount()，这些路由才会作为工具公开。否则将无法发现这些工具。
• 端口冲突： 后台进程（如 uvicorn）可能会占用端口。在 Windows 上，可以使用 netstat -ano | findstr "<PORT>" 查找进程 ID（PID），并使用 taskkill /F /PID <PID> 终止进程。有时需要稍等片刻或重启 IDE，操作系统才能完全释放端口。
• Cursor MCP 配置： 在 .cursor/mcp.json 中使用 url 键，可将 Cursor 连接到基于 HTTP 的 MCP 服务（例如 fastapi-mcp 提供的服务）。
• Agent 工具调用： Cursor Agent 通常会使用已配置的 MCP 服务；而专用的结对编程 AI 助手会通过自动生成的内部名称（例如 mcp_local-fastapi-mcp_read_root__get）与这些服务交互，而不是使用通用的工具调用函数。建立连接并发现工具后，在聊天中明确要求 Agent“使用该工具……”即可。

深入探索与功能（摘自 fastapi-mcp 文档）

本节概述了 fastapi-mcp 文档中的功能和概念。我们尚未实现这些内容，但了解它们会很有帮助。

身份验证与授权

fastapi-mcp 支持使用 FastAPI 依赖项进行身份验证，也支持 OAuth 2。

基本令牌透传：

• 初始阶段无需特殊的服务配置。

• MCP 客户端需要发送 Authorization 标头。通常可以通过 mcp-remote 之类的桥接工具来实现：

  {
    "mcpServers": {
      "remote-example": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "http://localhost:8000/mcp",
          "--header",
          "Authorization:${AUTH_HEADER}"
        ]
      },
      "env": {
        "AUTH_HEADER": "Bearer <your-token>"
      }
    }
  }
  

• 若要在 MCP 服务端_要求_身份验证，请向 AuthConfig 添加依赖项：

  from fastapi import Depends
  from fastapi_mcp import FastApiMCP, AuthConfig
  
  # Assuming verify_auth is your FastAPI dependency that checks the token
  mcp = FastApiMCP(
      app,
      auth_config=AuthConfig(
          dependencies=[Depends(verify_auth)],
      ),
  )
  

OAuth 2 流程：

• 完整支持 OAuth 2（MCP 规范 2025-03-26）。
• 需要为 AuthConfig 配置提供方详细信息（发行方、URL、客户端 ID/密钥）。
• 通常需要设置 setup_proxies=True，以处理标准 OAuth 提供方与 MCP 客户端预期之间的不兼容情况（例如缺少动态注册、范围处理方式不同）。

  mcp = FastApiMCP(
      app,
      auth_config=AuthConfig(
          issuer=f"https://auth.example.com/",
          authorize_url=f"https://auth.example.com/authorize",
          oauth_metadata_url=f"https://auth.example.com/.well-known/oauth-authorization-server",
          audience="my-audience",
          client_id="my-client-id",
          client_secret="my-client-secret",
          dependencies=[Depends(verify_auth)],
          setup_proxies=True, # Creates compatibility endpoints
      ),
  )
  

• 使用 mcp-remote 通常需要指定固定端口（mcp-remote ... 8080），以便在 OAuth 提供方中配置回调 URL（http://127.0.0.1:8080/oauth/callback）。

工具命名

• MCP 工具名称源自 FastAPI 路由的 operation_id。
• 如果未指定，FastAPI 会自动生成一个（例如 read_user_users__user_id__get）。
• 建议在 FastAPI 路由上设置明确的 operation_id，以使 MCP 工具名称更清晰：

  @app.get("/users/{user_id}", operation_id="get_user_info")
  async def read_user(user_id: int):
      # ...
  

刷新工具

• 如果在调用 mcp.mount()_之后_添加 FastAPI 路由，这些路由不会自动包含在内。

• 解决方法：定义新路由后再次调用 mcp.setup_server()。

  app = FastAPI()
  mcp = FastApiMCP(app)
  mcp.mount()
  
  @app.get("/new/endpoint", operation_id="new_tool")
  async def new_endpoint(): ...
  
  # Refresh the tools
  mcp.setup_server()
  

测试

• 可以使用 @modelcontextprotocol/inspector 工具测试 MCP 服务：

  # Run the inspector
  npx @modelcontextprotocol/inspector
  # Connect to your server URL (e.g., http://127.0.0.1:8000/mcp)
  # Use the UI to list and run tools.
  

部署

• 可以将从一个 FastAPI 应用（api_app）创建的 MCP 服务挂载到_另一个_FastAPI 应用（mcp_app），以便分开部署：

  api_app = FastAPI()
  # ... define API endpoints ...
  
  mcp_app = FastAPI()
  mcp = FastApiMCP(api_app) # Create from api_app
  mcp.mount(mcp_app) # Mount onto mcp_app
  
  # Run separately:
  # uvicorn main:api_app --port 8001
  # uvicorn main:mcp_app --port 8000
  

自定义

• 可在初始化 FastApiMCP 时设置服务名称/描述：

  mcp = FastApiMCP(
      app,
      name="My Custom MCP Name",
      description="Description for the server."
  )
  

• 可自定义工具/架构描述（例如，包含所有可能的响应）：

  mcp = FastApiMCP(
      app,
      describe_all_responses=True,
      describe_full_response_schema=True
  )
  

• 可在初始化 FastApiMCP 时使用 include_operations、exclude_operations、include_tags、exclude_tags 筛选公开的端点。

致谢

本项目在 AI 结对编程工具的协助下开发完成，其中包括集成在 Cursor 中的 Google Gemini 模型，以及用于研究和检索文档的 OpenAI ChatGPT。这些工具在整个过程中发挥了不可或缺的作用。