让你的服务变成MCP Server？FastAPI MCP 指南

在当今AI世界中，应用程序和大模型之间的无缝集成至关重要。模型上下文协议 (MCP) 通过允许 AI 模型访问外部工具和数据源来弥合这一差距。

FastAPI MCP 可以用最少的配置将现有的 FastAPI 端点转换为与 MCP 兼容的工具。本文将描述设置和使用 FastAPI MCP 来增强 AI 应用程序。作为一个零配置工具，它会自动将FastAPI 端点作为MCP工具公开。FastAPI MCP 的美妙之处在于其简单性，它使用现有的 API 端点，并使它们可供 AI 模型访问，而无需您重写代码或创建单独的实现。

1. FastAPI MCP 基础

借助 FastAPI MCP 服务器的支持，开发者可以更高效地将现有的 API 接口集成到 AI 模型的工作流中，从而实现模型对工具的智能调用。通过这一能力，FastAPI 不仅延续了其在构建高性能、易维护 API 方面的优势，还为 AI 应用提供了标准化、可扩展的接口接入方式。

使用 FastAPI MCP 的集成功能，可以轻松实现以下关键特性：

自动将 FastAPI 端点转换为 MCP 工具。这意味着你无需手动编写额外代码或重复定义接口逻辑，只需对现有端点稍作配置，即可将其注册为模型可调用的功能模块。这大大降低了将业务服务与 AI 模型连接的门槛。

无缝保留原有的 API 模式和文档。FastAPI 以其强大的类型注解和自动生成的交互式文档著称。在启用 MCP 功能后，这些优势依然得以保留——无论是请求体结构、响应格式还是验证规则，都将继续生效。同时，MCP 工具的描述信息也可以直接从 OpenAPI/Swagger 文档中提取，确保工具说明的一致性和准确性。

部署方式也具备高度灵活性。你可以选择将 MCP 服务器与现有 API 服务一起部署，形成一个统一的服务单元；也可以将其作为独立服务运行，以实现更清晰的职责划分和资源管理。这种灵活的架构设计，使得 FastAPI 可以适应从小型应用到企业级系统的多种部署需求。

不仅如此，还可以精细控制哪些端点被公开为 MCP 工具。并非所有 API 都适合暴露给 AI 模型，有些可能涉及内部逻辑或安全敏感操作。FastAPI 提供了便捷的机制，让你能够有选择性地指定需要注册为工具的端点，从而确保系统的安全性与可控性。

我们可以自定义工具说明的生成方式。包括工具名称、描述、参数格式、返回值结构等都可以根据实际业务场景进行调整。这种定制化能力不仅有助于提升模型对工具的理解效率，还能增强提示词工程中的语义一致性，使 AI 在调用工具时更加准确和可靠。

FastAPI MCP不仅简化了工具接入流程，还兼顾了开发效率、系统安全与模型可用性之间的平衡，是当前推动 AI 与业务服务深度融合的理想选择之一。

2. FastAPI MCP 的基本使用

在开始使用之前，需要安装 FastAPI MCP 包：

uv add fastapi-mcp
或者 pip install fastapi-mcp

实现 FastAPI MCP 的最简单方法是将其直接挂载到现有的 FastAPI 应用程序中。这里有一个最小的例子：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

# Your existing FastAPI app
app = FastAPI()

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

# Add MCP server to your FastAPI app
mcp = FastApiMCP(
    app,
    name="My API MCP",
    description="MCP server for my API",
    base_url="<http://localhost:8000>"
)

# Mount the MCP server to your app
mcp.mount()

# Run your app as usual
if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

通过这几行代码，你的 FastAPI 应用程序现在已经配备了一个 MCP 服务器，可以 http://localhost:8000/MCP 访问。支持 MCP 的 AI 模型，比如 Claude，现在可以作为工具发现 API 端点并与之交互。

3. 工具命名的最佳实践

当 AI 模型与我们的工具交互时，清晰的命名是必不可少的。FastAPI MCP 使用 FastAPI 路由中的 operation_id 作为 MCP 工具名。如果没有指定operation_id，FastAPI 会自动生成一个，但这个 id 可能用户友好性较差。

考虑以下两个端点定义：

# Auto-generated operation_id (e.g., "read_user_users__user_id__get")
@app.get("/users/{user_id}")
async def read_user(user_id: int):
    return {"user_id": user_id}

# Explicit operation_id (tool will be named "get_user_info")
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}

第二种方法创建一个更直观的工具名称，AI 模型将发现更容易正确使用。始终提供显式的 operation_id 值，以获得更清晰的工具名称。

4. 高级配置选项

FastAPI MCP 提供了控制如何将 API 模式描述为 AI 模型的选项： mcp = FastApiMCP( app, name="My API MCP", base_url="<http://localhost:8000>", describe_all_responses=True, # Include all possible response schemas describe_full_response_schema=True # Include full JSON schemas in descriptions ) describe_all_responses选项在工具描述中包含所有可能的响应模式，而 describe_full_response_schema 包含完整的 JSON 模式而不是简化版本。

如果不希望将所有 API 端点公开为 MCP 工具。FastAPI MCP 提供了几种过滤端点成为工具的方法：

# Only include specific operations
mcp = FastApiMCP(
    app,
    include_operations=["get_user", "create_user"]
)

# Exclude specific operations
mcp = FastApiMCP(
    app,
    exclude_operations=["delete_user"]
)

# Only include operations with specific tags
mcp = FastApiMCP(
    app,
    include_tags=["users", "public"]
)

# Exclude operations with specific tags
mcp = FastApiMCP(
    app,
    exclude_tags=["admin", "internal"]
)

# Combine operation IDs and tags
mcp = FastApiMCP(
    app,
    include_operations=["user_login"],
    include_tags=["public"]
)

这些过滤功能使我们能够细粒度地控制哪些端点作为工具公开，从而允许我们在维护安全性的同时为 AI 模型提供必要的功能。

5. 部署选项

虽然将 MCP 服务器挂载到现有的 FastAPI 应用程序很简单，但是出于安全或架构的原因，可能需要单独部署它。以下是如何设置：

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# Your API app
api_app = FastAPI()
# Define your API endpoints on api_app
@api_app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
    return {"user_id": user_id}
# A separate app for the MCP server
mcp_app = FastAPI()
# Create MCP server from the API app
mcp = FastApiMCP(
    api_app,
    base_url="<http://api-host:8001>"  # The URL where the API app will be running
)
# Mount the MCP server to the separate app
mcp.mount(mcp_app)

# 现在可以独立运行这两个服务了
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000

这种方法允许在不同的主机或端口上运行 API 和 MCP 服务器，从而在架构中提供灵活性。

6. 创建后更新工具

如果在创建 MCP 服务器之后向 FastAPI 应用程序添加新端点，则需要刷新服务器以包含它们：

# Create MCP server
mcp = FastApiMCP(app)
mcp.mount()

# Add new endpoints after MCP server creation
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Hello, world!"}

# Refresh the MCP server to include the new endpoint
mcp.setup_server()

# Add new endpoints after MCP server creation
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
    return {"message": "Hello, world!"}

# Refresh the MCP server to include the new endpoint
mcp.setup_server()

setup_server ()方法用任何新的端点更新 MCP 服务器，确保工具与 API 保持同步。

7. 将 AI 模型连接到 MCP 服务器

一旦集成了 MCP 的 FastAPI 应用程序运行起来，我们就可以通过各种方式将人工智能模型连接到它。

使用服务器发送的事件 (SSE)

许多 MCP 客户端 (如 Cursor) 支持服务器发送事件 (SSE) 进行实时通信：

• 在启用 FastAPI MCP 的情况下运行应用程序
• 在Cursor中，进入 Settings > MCP
• 使用 MCP 服务器的端点 (例如 http://localhost:8000/MCP) 作为 SSE URL
• Cursor 将自动发现所有可用的工具和资源

为其他客户端使用 MCP-Proxy

对于不直接支持 SSE 的客户端，可以使用 mcp-proxy:

• 安装 mcp-proxy: uv tool install mcp-proxy
• 将proxy配置添加到 Claude Desktop 的 MCP 配置文件

{
  "mcpServers": {
    "my-api-mcp-proxy": {
      "command": "/Full/Path/To/Your/Executable/mcp-proxy",
      "args": ["<http://127.0.0.1:8000/mcp>"]
    }
  }
}

8. 真实世界的应用和好处

FastAPI MCP 的出现，为将现有的 API 无缝集成到人工智能模型中提供了新的可能性。这种集成不仅简化了开发流程，还显著增强了 AI 模型的功能和应用场景。

它极大地扩展了数据访问的能力。通过 FastAPI MCP，AI 模型可以直接查询数据库或数据服务，获取所需的实时信息。这意味着无论是客户资料、交易记录还是市场趋势分析，模型都能迅速获得最新、最准确的数据支持，从而做出更加精准的预测和决策。

在文档处理方面，FastAPI MCP 允许模型在系统中执行添加、检索或分析文档的操作。例如，在法律行业，模型可以通过调用 API 来检索特定案件的相关文件；在医疗领域，则可以用于病历管理和诊断报告生成。这种能力使得 AI 不仅限于数据分析，还能深入到具体的业务操作层面，提供更为全面的服务。

FastAPI MCP 支持复杂的业务逻辑执行。通过 API，AI 模型能够触发一系列预定义的业务流程，如订单处理、库存管理或财务结算等。这不仅提高了自动化水平，也确保了操作的一致性和准确性，减少了人为错误的可能性。

FastAPI MCP 还促进了用户交互的发展，使 AI 驱动的应用程序能够以更加自然、高效的方式与用户进行互动。无论是在客户服务中的智能应答，还是个性化推荐系统的优化，MCP 都能提供强大的技术支持，提升用户体验。

使用 FastAPI MCP 的主要优点体现在以下几个方面：

1. 开发效率的提升。开发者无需从零开始构建专门的集成接口，而是可以直接重用现有的 API。这种方式不仅节省了大量的时间和资源，还加快了项目的推进速度。

2. 一致性。由于所有的 API 逻辑都维护在一个单一的真实来源中，任何更新或修改都会自动同步到所有相关的应用和服务，包括那些由 AI 模型使用的部分。这确保了整个系统的稳定性和一致性，减少了维护成本。

3.简单维护。当 API 发生变化时，这些变更会自动反映在 MCP 工具中，无需手动调整每个集成点。这对于需要频繁迭代和升级的系统来说尤为重要，能够有效避免因版本不匹配导致的问题。

4. 安全性。FastAPI MCP 提供了精细的控制机制，允许开发者明确指定哪些端点可以被 AI 模型访问。这样既能保证数据的安全性，又能灵活应对不同的应用场景需求。

FastAPI MCP 不仅为 AI 模型与现有 API 的集成开辟了新路径，还在多个关键领域展现了其独特价值，包括数据访问、文档处理、业务逻辑执行以及用户交互优化。同时，它带来的开发效率、一致性、维护简便性和安全性方面的优势。

如果希望快速入门MCP，建议阅读老码农的新作——

如果希望了解MCP 更多的应用价值，建议阅读：

9. 小结

FastAPI MCP 标志着在实现 API 与人工智能模型之间无缝、高效集成方面迈出的关键一步。它通过自动化地将 FastAPI 端点转化为符合 MCP 规范的工具，有效避免了重复开发的工作量，显著降低了构建 AI 增强型应用的技术门槛和复杂度。

无论开发一个简单的原型，还是打造一个面向生产的复杂系统，FastAPI MCP 都能提供足够的灵活性与精细的控制能力，帮助您高效地将现有 API 功能安全、准确地暴露给 AI 模型使用。借助本指南中所介绍的最佳实践，您可以充分发挥 MCP 在智能服务构建中的潜力，提升应用的自动化水平与智能化能力。

现在就开始让我们将API 与 AI 模型集成，释放前所未有的自动化潜能，开启更智能、更流畅的用户体验之旅。