FastMCP 2.x 干货笔记之 FastMCP 服务端部署：HTTP 部署指南与 TaoToken 统一 Key 配置

1. 从 STDIO 到 HTTPFastMCP 服务端为什么要换传输方式FastMCP 2.x 默认用 STDIO 传输本地开发时确实省事——进程间管道通信不用管端口、不用管网络。但一旦你想让多个客户端同时连、想让服务跑在远程机器上、想和云端 LLM 应用对接STDIO 就顶不住了。HTTP 部署就是解决这个问题的把 MCP 服务器变成一个可通过 URL 访问的远程服务任何能发 HTTP 请求的客户端都能连上来。这篇笔记聚焦 FastMCP 2.x 服务端 HTTP 部署的完整链路从直接 HTTP 服务器到 ASGI 应用从自定义路径到健康检查再到接入 TaoToken 统一 Key 的配置文件骨架。适合已经跑通过本地 STDIO 版本、准备把 MCP 服务推到远程或容器里的开发者。部署完成后我会给出一套 curl 验证动作让你快速确认服务连通性而不是靠猜。FastMCP 提供两种 HTTP 部署方式选哪种取决于你的场景。直接 HTTP 服务器方法最简单改一下run()的参数就行FastMCP 自己处理 Web 服务器配置适合独立部署、内部工具、开发环境。ASGI 应用程序方法更灵活生成标准 ASGI app可以配 Uvicorn、Gunicorn、Hypercorn支持多工作进程、自定义中间件、和现有 Web 框架集成生产环境首选。2. TaoToken 前置统一 Key 与 API 通道准备在部署 HTTP 服务之前先把模型调用的通道理清楚。FastMCP 服务端本身不绑定模型但你的工具函数里大概率会调 LLM——这时候用 TaoToken 的统一 Key 可以省掉每个工具单独配 Key 的麻烦。TaoToken 的定位是统一 API 通道一个 Key 走多个模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端点是 https://taotoken.net/api 。你需要先去控制台创建一个 API Key然后把它写进环境变量而不是硬编码在代码里。具体操作路径打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建 Key然后在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 管理你的 Key 列表。如果你打算长期跑编码类 Agent可以看看 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 的套餐只是想验证模型连通性用 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 的对话页面就够了。注意API Key 只放在服务端环境变量里不要写进前端代码或提交到 Git。HTTP 部署后服务端暴露在网络上Key 泄露风险比本地高得多。3. 可复制配置settings.json 与 config.toml 骨架3.1 直接 HTTP 服务器的最小实现先写一个最简单的 server.py用内置run()方法启动 HTTP 传输from fastmcp import FastMCP mcp FastMCP(我的服务器) mcp.tool def process_data(input: str) - str: 在服务器上处理数据 return f已处理{input} if __name__ __main__: mcp.run(transporthttp, host0.0.0.0, port8000)运行python server.py服务器就在http://localhost:8000/mcp可访问了。host0.0.0.0表示监听所有网卡远程机器也能连如果只想本机访问改成127.0.0.1。3.2 ASGI 应用方式生产环境用 ASGI 方式先生成 app 对象from fastmcp import FastMCP mcp FastMCP(我的服务器) mcp.tool def process_data(input: str) - str: 在服务器上处理数据 return f已处理{input} app mcp.http_app()然后用 Uvicorn 启动uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4--workers 4开四个工作进程处理并发请求生产环境按 CPU 核数调整。3.3 自定义路径与健康检查默认路径是/mcp/想改成/api/mcp/就在http_app()里传path参数app mcp.http_app(path/api/mcp/)健康检查端点用mcp.custom_route加from starlette.responses import JSONResponse mcp.custom_route(/health, methods[GET]) async def health_check(request): return JSONResponse({status: healthy, service: mcp-server})这样http://localhost:8000/health就能被负载均衡器或监控系统探测。3.4 settings.json 骨架如果你用 Claude Code 或类似客户端连接远程 MCP 服务settings.json 里这样配{ mcpServers: { my-remote-server: { type: http, url: http://your-server-ip:8000/mcp, headers: { Authorization: Bearer ${MCP_AUTH_TOKEN} } } } }${MCP_AUTH_TOKEN}从环境变量读取不要写死。url换成你实际部署的地址和路径。3.5 config.toml 骨架有些工具用 TOML 格式配置骨架如下[mcp_servers.my-remote-server] type http url http://your-server-ip:8000/mcp [mcp_servers.my-remote-server.headers] Authorization Bearer ${MCP_AUTH_TOKEN}3.6 接入 TaoToken 的环境变量配置在服务端代码里调 TaoToken API 时用环境变量传 Keyimport os from openai import OpenAI client OpenAI( base_urlhttps://taotoken.net/api, api_keyos.environ.get(TAOTOKEN_API_KEY) )启动服务时传入TAOTOKEN_API_KEYyour_key_here uvicorn app:app --host 0.0.0.0 --port 8000这样代码里不出现明文 Key换环境只改环境变量。4. 验证请求curl 确认服务连通性部署完别急着接客户端先用 curl 确认服务活着。4.1 健康检查curl -s http://localhost:8000/health预期返回{status: healthy, service: mcp-server}如果返回 404检查mcp.custom_route有没有加在mcp对象上以及路径有没有拼错。4.2 MCP 端点探测MCP 协议端点用 POST 请求发一个初始化消息curl -s -X POST http://localhost:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d { jsonrpc: 2.0, id: 1, method: initialize, params: { protocolVersion: 2024-11-05, capabilities: {}, clientInfo: {name: curl-test, version: 1.0} } }如果服务正常会返回一个 JSON-RPC 响应包含serverInfo和capabilities。返回 406 通常是Accept头没带text/event-stream返回 401 说明配了认证但没带 Token。4.3 带认证的请求如果服务端配了 Bearer Token 认证curl -s -X POST http://localhost:8000/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -H Authorization: Bearer your_token_here \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2024-11-05,capabilities:{},clientInfo:{name:curl-test,version:1.0}}}4.4 远程访问验证从另一台机器测试curl -s http://your-server-ip:8000/health连不上先查防火墙和安全组有没有放行 8000 端口再确认host参数是不是0.0.0.0。5. 本篇常见错排查5.1 端口被占用启动时报Address already in use换端口或杀掉占用进程lsof -i :8000 kill -9 PID5.2 路径双前缀挂载到 Starlette 子应用时base_url和mcp_path都带前缀会导致/api/api/mcp。记住挂载前缀只放base_urlmcp_path只写内部路径。5.3 CORS 报错浏览器客户端连不上控制台报 CORS 错误。加 CORS 中间件from starlette.middleware import Middleware from starlette.middleware.cors import CORSMiddleware middleware [ Middleware( CORSMiddleware, allow_origins[http://localhost:3000], allow_methods[GET, POST, DELETE, OPTIONS], allow_headers[mcp-protocol-version, mcp-session-id, Authorization, Content-Type], expose_headers[mcp-session-id], ) ] app mcp.http_app(middlewaremiddleware)生产环境别用allow_origins[*]指定确切来源。5.4 会话 ID 读不到浏览器收到响应但 JavaScript 拿不到mcp-session-id检查expose_headers有没有包含它。没有这个配置浏览器能收到 header 但 JS 访问不了会话管理直接失败。5.5 lifespan 没传导致会话管理器初始化失败挂载到 Starlette 时忘了传lifespanmcp_app.lifespan流式 HTTP 传输会报错。嵌套生命周期不被识别必须显式传递。5.6 认证配置了但客户端连不上先确认 Token 有没有过期再检查Authorization头格式是不是Bearer token。有些客户端要求远程服务器必须认证没配就直接拒绝连接。6. 部署完成后的接入选择服务跑起来、curl 验证通过之后接下来看你的使用场景选接入方式。如果你只是想在对话里验证模型能不能正常调工具打开 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接试。如果你要把这个 HTTP MCP 服务接进编码工作流长期跑 Agent 任务建议先配好 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 的套餐再把 Key 写进环境变量。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各客户端的详细配置示例。Key 管理统一走 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 别把 Key 散落在多个配置文件里。部署 HTTP 服务最容易踩的坑不是代码写错而是网络和认证配置。先把/health跑通再用 curl 发 initialize 请求确认 MCP 协议层正常最后才接客户端。这个顺序能帮你快速定位问题出在哪一层。