1. FastAPI-MCP 报 Missing parameter 到底卡在哪如果你正在照着 FastAPI-MCP 的示例搭 MCP Server多半会遇到这个报错{status: error, message: Missing parameter: userId}。请求明明带了service_nameUserInfoServicemethod_namegetUserInfocurl 也返回 200但data里就是空的或者直接告诉你少参数。这个问题的本质不是 MCP 协议本身有问题而是convert_to_mcp里的参数校验逻辑、services列表定义、以及你实际发出去的 query string 三者没有对齐。FastAPI-MCP 这类转换工具做的事情是把已有的服务接口映射成 MCP 兼容的 Tool 或 Resource。它会在convert_to_mcp里做三件事按service_name找服务、按method_name找方法、遍历method[parameters]检查每个参数是否出现在kwargs里。只要有一个参数名对不上就抛Missing parameter。很多人卡住的原因是services列表里写的是userId但 curl 里传的是user_id或者方法定义里参数是必填但请求里漏了再或者**kwargs在 FastAPI 的 query 解析里没有正确接住额外字段。这篇排障视角的文章不把 FastAPI-MCP 或call_service换成别的通道而是先解决“谁来帮你逐段核对代码”的问题。我的做法是打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建一个 Key然后把 Codex 的 Base URL 配成 https://taotoken.net/api 让 Codex 对照原文代码检查参数校验、适配器返回结构和 curl 的预期结果。TaoToken 在这里只提供模型通道的 Key 和 Base URL不参与 MCP 协议转换逻辑也不碰你的services列表和call_service实现。配通之后你就可以用 Codex 逐段核对 FastAPI-MCP 的报错与返回值把“少传 userId”这类问题定位到具体行。2. 先给 Codex 配好 TaoToken 的 Key 和 Base URL排障之前得先让 Codex 能稳定读到你的项目代码并给出可执行的修改建议。这里不涉及任何协议转换只是把模型通道配通。你可以在 https://taotoken.net/api-keys 创建 API Key然后在 Codex 的配置里把 Base URL 指向 https://taotoken.net/api 。如果你用的是 Claude Code 这类终端编码工具也可以在 https://taotoken.net/claude-code-anthropic 找到对应的接入方式长期做编码和 Agent 任务的话可以看看 https://taotoken.net/coding-plan 的额度方案避免排障到一半 Key 不够用。配置时注意两点第一Base URL 只填到https://taotoken.net/api不要自己拼/v1或/chat/completions具体路径由客户端决定第二Key 放在环境变量里不要硬编码进main.py。你可以这样写一个.env# .env TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api然后在 Codex 的配置文件里引用这两个变量。配好之后先用一个最小请求验证通道是否通curl -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-4o-mini, messages: [{role: user, content: 只回复 ok}] }如果返回里有choices字段说明模型通道已经通了。这一步和 MCP 协议无关只是保证 Codex 能正常工作。接下来才是让它去读你的 FastAPI-MCP 代码。3. 可复制配置让 Codex 对照 services 列表和 convert_to_mcp 校验现在把 Codex 指向你的项目目录让它逐段核对。你可以直接在 Codex 里贴下面这段提示词把文件路径换成你自己的请阅读 main.py 中的 services 列表、convert_to_mcp 函数和 call_service 函数。 重点检查 1. services 里每个 method 的 parameters 名称和 curl 请求里的 query 参数名是否完全一致 2. convert_to_mcp 里 for param in method[parameters] 的校验逻辑是否把可选参数也当成必填 3. **kwargs 在 FastAPI 的 async def convert_to_mcp(service_name: str, method_name: str, **kwargs) 中是否能接住 userId 4. call_service 返回的 dict 结构和 curl 预期结果里的 data 字段是否对得上。 不要改代码先列出所有不一致的地方。我试过让 Codex 直接读services列表它很快就能指出parameters里写的是{name: userId, type: str}但 curl 里如果写成user_id123kwargs里就是user_id校验时param[name] not in kwargs成立于是抛Missing parameter: userId。这就是最常见的错位。为了让你能直接复现这里给一份最小可运行的main.py把services和校验逻辑都写清楚from fastapi import FastAPI import uvicorn app FastAPI() services [ { service_name: UserInfoService, methods: [ { method_name: getUserInfo, parameters: [ {name: userId, type: str, required: True} ], return_type: UserInfo } ] } ] app.get(/mcp) async def convert_to_mcp(service_name: str, method_name: str, **kwargs): try: service next( (s for s in services if s[service_name] service_name), None ) if service is None: raise ValueError(fUnknown service: {service_name}) method next( (m for m in service[methods] if m[method_name] method_name), None ) if method is None: raise ValueError(fUnknown method: {method_name}) for param in method[parameters]: if param.get(required, True) and param[name] not in kwargs: raise ValueError(fMissing parameter: {param[name]}) result call_service(service_name, method_name, **kwargs) return {status: success, data: result} except Exception as e: return {status: error, message: str(e)} def call_service(service_name: str, method_name: str, **kwargs): return { service: service_name, method: method_name, parameters: kwargs } if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)注意parameters里我加了required字段。原文示例里没有这个字段导致所有参数都被当成必填。如果你希望userId可选就得在convert_to_mcp里判断param.get(required, True)而不是无条件抛错。Codex 在核对时会帮你把这类逻辑差异标出来。4. 验证请求curl 结果和预期返回值对齐配好代码后用 curl 发一次请求看返回是否和预期一致。启动服务uvicorn main:app --reload --port 8000然后发请求curl -X GET http://localhost:8000/mcp?service_nameUserInfoServicemethod_namegetUserInfouserId123预期返回{ status: success, data: { service: UserInfoService, method: getUserInfo, parameters: { userId: 123 } } }如果你拿到的是{status: error, message: Missing parameter: userId}说明kwargs里没有userId。这时候让 Codex 检查两件事第一curl 里的参数名是否和services里的name完全一致大小写敏感第二FastAPI 的**kwargs是否被其他中间件或依赖改写过。实测下来90% 的Missing parameter都是参数名拼写或大小写不一致导致的。还有一种情况curl 返回 200但data里parameters是空的。这通常是因为call_service里用了kwargs.get(userId)但实际传进来的是user_id或者convert_to_mcp在调用call_service时没有把kwargs透传下去。Codex 可以帮你逐行比对convert_to_mcp的result call_service(service_name, method_name, **kwargs)这一行确认没有漏掉**。如果你想让 Codex 直接模拟一次请求并对比返回可以在 Codex 里贴请根据 main.py 里的 services 和 convert_to_mcp模拟 curl -X GET http://localhost:8000/mcp?service_nameUserInfoServicemethod_namegetUserInfouserId123 的完整执行路径逐步打印 kwargs、校验结果和 call_service 的返回值。这样你就能看到kwargs在每一步的实际内容定位到是哪一步丢了userId。5. 本篇常见错排查services 列表、参数映射、curl 对不上排障时按下面这个顺序查基本能覆盖所有Missing parameter场景。第一检查services列表里的service_name和method_name是否和请求里完全一致。FastAPI 的 query 参数是大小写敏感的UserInfoService和userinfoservice会被当成两个不同的服务。Codex 可以帮你把services里所有名称列出来和 curl 里的值做 diff。第二检查parameters里的name和 curl 里的 query key 是否一致。常见错误是userId写成user_id、userid或userID。如果你用的是前端或 Postman还要注意 URL 编码userId123不会被编码但如果有特殊字符就要小心。第三检查convert_to_mcp的校验逻辑是否把可选参数当成必填。原文示例里没有required字段所有参数都会被强制校验。你可以让 Codex 把for param in method[parameters]改成先判断param.get(required, True)这样可选参数就不会误报。第四检查call_service的返回结构是否和预期一致。如果call_service返回的是{userId: kwargs.get(userId), ...}而你的 curl 预期是{service: ..., method: ..., parameters: ...}那就要统一返回格式。Codex 可以帮你把两边对齐。第五检查 FastAPI 的**kwargs是否被 Pydantic 模型或依赖注入拦截。如果你在convert_to_mcp上加了Depends或者用了Request对象kwargs可能拿不到 query 参数。这时候让 Codex 检查函数签名确保service_name、method_name和**kwargs都是直接从 query 解析的。如果你在排障过程中需要查 MCP 协议本身的定义可以在 https://taotoken.net/doc 找到接入文档如果只是想快速验证某个模型对代码的理解可以用 https://taotoken.net/models 的模型对话功能把报错和代码贴进去让它分析。注意TaoToken 只提供模型通道不参与 MCP 协议转换所以services列表和call_service的实现还是得在你的项目里改。6. 配通之后用 Codex 逐段核对报错与返回值当 Codex 的 Base URL 配成 https://taotoken.net/api 并且 Key 可用之后你就可以把它当成一个“代码核对助手”而不是让它去替代 FastAPI-MCP。具体做法是把main.py全文贴给 Codex然后按下面这个顺序让它输出核对结果。第一步让它列出services里所有service_name、method_name和parameters[].name生成一张对照表。第二步让它模拟curl -X GET .../mcp?service_nameUserInfoServicemethod_namegetUserInfouserId123的执行路径打印每一步的kwargs和校验结果。第三步让它对比call_service的返回结构和 curl 预期结果标出字段差异。第四步如果还有Missing parameter让它给出最小修改 diff只改参数校验或参数名映射不动 MCP 协议转换逻辑。这样做的原因是FastAPI-MCP 的报错往往不是协议设计问题而是参数映射的细节问题。Codex 擅长逐行比对和模拟执行能快速定位到userId是在哪一步丢的。TaoToken 在这里的角色只是提供模型通道的 Key 和 Base URL让你能稳定调用 Codex 做代码核对。配通之后你可以反复用同一套提示词检查不同的service_name和method_name把Missing parameter的排查时间从半小时压缩到几分钟。最后提醒一点如果你在 curl 里传了userId123但services里定义的是user_id不要急着改 curl而是先统一命名规范。Codex 可以帮你把services里的name改成和 curl 一致或者在convert_to_mcp里加一层别名映射。改完之后重新跑一次 curl确认返回的data.parameters里有userId就说明参数校验和适配器返回结构都对上了。