解决90%开发痛点：FastAPI-MCP常见问题与实战指南
项目地址: https://gitcode.com/GitHub_Trending/fa/fastapi_mcp 你是否在使用FastAPI-MCP时遇到过工具不显示、请求超时或自定义功能受阻的问题？本文汇总开发者最常遇到的5类核心问题，提供经过官方验证的解决方案和代码示例，帮助你20分钟内解决90%的集成难题。读完本文你将掌握：HTTP超时配置、动态工具注册、自定义工具实现、MCP服务器测试和调试技巧。
配置HTTP请求超时
默认情况下，FastAPI-MCP的HTTP请求超时时间为5秒。当你的API端点需要更长响应时间时，可以通过注入自定义httpx客户端来配置超时时间。
from examples.shared.apps.items import app # 导入FastAPI应用
from examples.shared.setup import setup_logging
import httpx
from fastapi_mcp import FastApiMCP
setup_logging()
# 配置20秒超时的HTTP客户端
mcp = FastApiMCP(app, http_client=httpx.AsyncClient(timeout=20))
mcp.mount_http()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
完整示例代码：examples/07_configure_http_timeout_example.py
工具未显示在MCP检查器中
当你在创建并挂载MCP服务器后添加端点时，新端点不会自动注册为工具。有两种解决方案：
方案一：调整代码顺序
将MCP创建代码移至所有端点定义之后。
方案二：重新注册工具
调用mcp.setup_server()方法重新注册所有工具。
from examples.shared.apps.items import app
from examples.shared.setup import setup_logging
from fastapi_mcp import FastApiMCP
setup_logging()
mcp = FastApiMCP(app) # 创建MCP服务器
mcp.mount_http() # 挂载MCP服务器
# 在MCP创建后添加新端点
@app.get("/new/endpoint/", operation_id="new_endpoint", response_model=dict[str, str])
async def new_endpoint():
return {"message": "Hello, world!"}
# 重新注册工具以包含新端点
mcp.setup_server()
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
完整示例代码：examples/05_reregister_tools_example.py
添加非FastAPI端点的自定义工具
目前FastAPI-MCP仅支持从FastAPI端点派生的工具。若需添加不对应API端点的自定义功能，可通过创建FastAPI端点包装自定义功能来实现。
实现步骤：
- 创建一个FastAPI端点作为自定义工具的包装器
- 在端点函数中实现自定义逻辑
- 确保端点有正确的
operation_id和响应模型
测试MCP服务器是否正常工作
要验证MCP服务器是否正常工作并检查工具是否正确公开，可以使用MCP检查器工具：
- 启动FastAPI应用
- 打开新终端，运行MCP检查器：
npx @modelcontextprotocol/inspector - 输入MCP服务器的挂载路径URL（默认：
http://127.0.0.1:8000/mcp） - 导航到"Tools"部分，点击"List Tools"查看所有可用端点
- 测试端点：
- 从列表中选择工具
- 填写所需参数
- 点击"Run Tool"执行
获取帮助与支持
如果遇到本文未涵盖的问题，可以通过以下渠道获取帮助：
- 查阅官方文档：docs/getting-started/FAQ.mdx
- 在GitHub上提交issue
- 加入社区聊天：MCParty Slack社区
希望本文能帮助你解决使用FastAPI-MCP时遇到的问题。如果有其他疑问或建议，欢迎在项目仓库提交issue或参与社区讨论。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
