1. 造数服务为什么要接 MCP从六步手工到一句话搞定社区造数服务接入 MCP 这件事本质上解决的是一个很具体的痛点测试数据准备太碎、太依赖人。你回想一下日常联调场景要造一个「团长拉新」的账号得先确认这个号 30 天内没发过动态再把它加进团队 A然后发一条动态接着过一审风控、过二审标注最后还得把阅读数刷到 300。这一串操作分散在造数工厂、接口自动化平台、脚本仓库里六个步骤走下来不熟悉业务的人根本串不起来。MCPModel Context Protocol能做什么它把工具能力标准化暴露给 AI Agent让 Agent 自己决定调哪个接口、按什么顺序调。适合谁适合所有手里有一堆内部工具、想让 AI 帮忙编排的研发和测试同学。我这次落地的就是把基于 FastAPI 的社区造数服务通过 fastapi-mcp 这个库暴露成 MCP 工具Agent 在本地开发与联调时可以直接调用。整条链路的关键词是FastAPI 提供 HTTP 接口fastapi-mcp 把这些接口自动转成 MCP 工具uv 负责依赖和环境管理AI Agent比如 Cursor 里的 Agent负责按自然语言编排调用。你不需要重写业务逻辑只需要在启动入口挂载一下 MCP再给每个接口补上清晰的 operation_id 和文档注释。下面我按「环境准备 → 配置挂载 → 验证调用 → 排错」的顺序把可复制的步骤全部摊开。2. 用 uv 初始化造数服务环境与依赖锁定造数服务原本用 pip 或 poetry 管理依赖这次我换成 uv实测下来环境隔离更干净装包速度也快。第一步是安装 uv官方脚本一行搞定curl -LsSf https://astral.sh/uv/install.sh | sh装完之后创建虚拟环境指定 Python 3.12因为 fastapi-mcp 对版本有要求uv venv tools_venv --python 3.12 source tools_venv/bin/activate激活后安装依赖。这里有个坑如果你直接uv pip install -r pyproject.toml某些版本的 uv 对 pyproject 的解析行为和 requirements.txt 不完全一致建议用uv sync或者明确指定依赖文件。我这边是把核心库版本锁死在 pyproject.toml 里避免 fastapi-mcp 和 mcp 版本错配[project] name community-tools-mcp version 0.1.0 requires-python 3.12 dependencies [ fastapi0.115.12, fastapi-mcp0.3.1, mcp1.7.0, pydantic2.11.0, pydantic-settings2.2.0, uvicorn0.30.0, httpx0.27.0, ]锁定版本这件事别偷懒。fastapi-mcp 0.3.1 依赖的 mcp 是 1.7.0如果你环境里已经装了别的 mcp 版本启动时会报ImportError: cannot import name FastMCP之类的错。用 uv 的好处是它会按 lock 文件解析冲突会提前告诉你。项目结构保持原样即可MCP 改造不涉及目录大改├── main.py # 启动入口MCP 挂载在这里 ├── pyproject.toml # 依赖与版本锁定 ├── app │ ├── api # 造数接口目录 │ ├── core # 全局配置 │ ├── crud # 增删改查 │ ├── models # 表结构 │ └── schemas # pydantic 模型 └── alembic # 数据库迁移环境准备好之后先别急着改 MCP跑一遍原有服务确认基线正常。启动命令uvicorn main:app --host 0.0.0.0 --port 8023 --reload访问http://localhost:8023/docs能看到 Swagger 文档说明造数服务本身没问题。这一步是后面排错的参照物如果 MCP 挂了但 Swagger 正常问题一定出在挂载层。3. 可复制配置main.py 挂载 fastapi-mcp 与 settings 片段真正接入只需要三步。第一步引入库第二步在 main.py 里创建 FastApiMCP 实例并 mount第三步给造数接口补 operation_id 和文档注释。先看 main.py 的完整可复制片段from fastapi import FastAPI import uvicorn from fastapi_mcp import FastApiMCP app FastAPI(title社区造数服务, description社区测试数据构造工具集) # 注册原有造数路由 from app.api import tools_router app.include_router(tools_router, prefix/tools) # 基于 FastAPI app 创建 MCP server mcp FastApiMCP( app, namecommunity-tools-mcp, description社区造数 MCP 服务支持账号、动态、风控等造数能力, describe_all_responsesTrue, describe_full_response_schemaTrue, ) # 挂载到 /mcp 路径 mcp.mount() if __name__ __main__: uvicorn.run(main:app, host0.0.0.0, port8023, reloadTrue, workers2)这里几个参数值得说清楚。name和description会出现在 MCP 客户端的工具列表里写清楚有助于 Agent 判断该不该用这个服务。describe_all_responsesTrue会把所有可能的响应 schema 塞进工具描述Agent 能更准确理解返回结构代价是描述变长、token 消耗增加。describe_full_response_schemaTrue类似把完整 JSON schema 带上。我建议本地开发环境两个都开线上按需关掉省 token。如果你只想暴露部分接口用 include/exclude 控制mcp FastApiMCP( app, include_tags[tools, public], exclude_operations[delete_account], )注意include_operations和exclude_operations不能同时用include_tags和exclude_tags也不能同时用但 operations 和 tags 可以组合匹配任一条件即暴露。第三步是工作量最大但最影响效果的一步给每个造数接口显式命名 operation_id并写清楚文档注释。FastAPI 路由如果不指定 operation_id框架会自动生成类似read_user_users__user_id__get的名字Agent 看了容易懵。显式命名后工具名就是 operation_idrouter.post(/create-account, operation_idcreate_account, summary创建测试账号) async def create_account( env: str Body(..., description环境默认 t1), phonenumber: str Body(None, description手机号非必填不填自动生成), pwd: str Body(test123, description密码默认 test123), usernum: str Body(None, description数量), ): 创建测试账号默认 111 开头不用填写 111只需要后面 8 位。 不传 phonenumber 时默认随机生成手机号。 ...注释里把「默认值」「是否必填」「格式要求」写全Agent 的调用准确率会明显提升。这部分后面排错章节会展开讲。4. 验证请求MCP 工具发现与一次造数调用链路配置挂载完启动服务uvicorn main:app --host 0.0.0.0 --port 8023 --reload控制台无报错后MCP server 就在http://localhost:8023/mcp。接下来用 MCP 客户端连接。以 Cursor 为例在项目根目录建.cursor/mcp.json{ mcpServers: { community-tools-mcp: { url: http://localhost:8023/mcp, description: 本地社区造数 MCP 服务 } } }打开 Cursor Settings → MCP能看到community-tools-mcp加载出来开关打开显示绿色说明工具发现成功。点开工具列表应该能看到create_account、publish_post、pass_risk_review等 operation_id 对应的工具。现在做一次真实调用验证。在 Cursor 的 Agent 对话里输入给手机号 11120210001 的用户发布一个点评动态并且通过风控一审。注意 11120210001 是手机号不是 userId。Agent 会自动编排三步先调get_user_info用手机号换 userId再调publish_post用 userId 发动态最后调pass_risk_review用动态 id 过一审。你可以在 Cursor 的调用日志里看到每次 tool call 的入参和返回。如果三步都返回成功说明工具发现和调用链路完全打通。再验证一个批量场景随机创建 10 个测试账号。如果 Agent 报错大概率是注释没写清楚。我第一次跑这个需求时Agent 自作主张传了个手机号进去结果接口 500。排查发现 t1 环境测试账号默认填了 111 前缀只需要传后 8 位而 Agent 不知道这个规则。把注释改成「默认 111 开头不用填写 111只需要后面 8 位不传 phonenumber 默认随机生成」之后再跑就成功了。这个案例说明MCP 接入的准确率七分靠注释三分靠模型。5. 本篇常见错排查401、local proxy failed 与 reading choices接入过程中我踩了几个典型报错这里按现象、原因、解法列出来你遇到时可以直接对照。报错一401 Unauthorized。如果你在 Cursor 里连的是线上造数服务而线上挂了鉴权MCP 请求会返回 401。fastapi-mcp 支持 auth_config 参数但更简单的做法是本地开发连本地服务线上服务单独配一个带 token 的 header。检查你的 mcp.json 里 url 是否指向了需要鉴权的地址。报错二local proxy failed / connection refused。这个通常是 MCP server 没起来或者端口不对。先确认uvicorn进程还在再curl http://localhost:8023/mcp看是否有响应。如果 Swagger 能访问但 /mcp 404说明mcp.mount()没执行到检查 main.py 里 mount 是否在 include_router 之后。报错三Error reading choices / unexpected token。这个多出现在 Agent 调用工具后解析返回时。原因是接口返回了非 JSON 结构或者返回体太大超出模型上下文。解法是给造数接口统一返回结构并在 FastApiMCP 里关掉describe_full_response_schema减少描述体积。报错四OAuth / auth.json 相关。如果你用的是 Codex 或 Claude Code 这类需要 auth.json 的客户端MCP 配置要写全三件套Base URL、Key、Model ID。以 Codex 的 auth.json 为例{ base_url: https://taotoken.net/api, api_key: sk-你的key, model: claude-sonnet-4-5 }Base URL 填https://taotoken.net/apiKey 在控制台生成Model ID 按你实际用的模型填。三者缺一客户端会报 OAuth 或 401。如果你用的是 Claude Code 做代码润色类任务同样需要先完成这套接入配置否则「连上就能用」只是错觉。报错五工具列表为空。Cursor 里 MCP 显示绿色但工具列表空通常是 operation_id 重复或路由没注册。检查是否有两个接口用了同一个 operation_idFastAPI 会静默覆盖。6. 语义一致 CTA把造数 MCP 接到你的 Agent 工作流造数服务接入 MCP 之后下一步就是把它接到你日常的 Agent 工作流里。如果你只是本地联调验证直接用 Cursor 连本地/mcp就够了。如果你想让团队共用可以把服务部署到内网然后在 mcp.json 里换成内网地址。需要生成和管理 API Key 的话去控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole接入文档里有完整的 Base URL 和鉴权说明https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你要长期跑编码类 Agent 任务比如让 Agent 自动编排造数、跑回归Coding Plan 更划算https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan想先验证模型对话效果可以直接在模型对话页试https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchatAPI Key 管理入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keysClaude Code 接入参考https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaudecode最后说个实操经验造数接口的文档注释不是写一次就完事。每次 Agent 调用出错先去看它传了什么参数、接口返回了什么然后回头改注释。我前后改了四版注释create_account的调用成功率才从一半提到稳定。注释即规范这句话在 MCP 场景下是实打实的。