MCP Python SDK 排错指南：从 traceback 最后一行到根因的逐一排查-北京尧图网络

人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载导读本文是 python-sdkModel Context Protocol 官方 Python SDK的实战排错手册页面中每一节标题都对应 SDK 实际产出的一行错误消息原文依次给出它的真实含义与一步到位的修复方法。读完本文你将掌握 13 类高频报错的定位思路——从 anyio 的ExceptionGroup包装、工具调用失败的正确捕获姿势到 421 Host 校验、Session 失效、elicitation 无回程通道、requestState 多进程签名不一致等——并能用浏览器页内查找直接定位自己 traceback或服务器日志的最后一行。文中引用的每一条错误都真实可复现SDK 自身的测试套件逐一覆盖了它们见 tests/docs_src/test_troubleshooting.py。演示服务器一份可复现全部错误的代码多个条目都针对同一台服务器运行它注册了一个工具和一个模板化资源遇到未知城市时各自抛出异常。完整代码见 docs_src/troubleshooting/tutorial001.pyfrom mcp.server import MCPServer from mcp.server.mcpserver.exceptions import ResourceNotFoundError, ToolError mcp MCPServer(Weather) FORECASTS {London: Rain., Cairo: Sun.} mcp.tool() def forecast(city: str) - str: Todays forecast for one city. if city not in FORECASTS: raise ToolError(fNo forecast for {city!r}.) return FORECASTS[city] mcp.resource(weather://{city}) def report(city: str) - str: The full report for one city. if city not in FORECASTS: raise ResourceNotFoundError(fNo forecast for {city!r}.) return f{city}: {FORECASTS[city]}各条目通过http://localhost:8000/mcp访问它因此请用 HTTP 方式把它跑起来uv run mcp run server.py --transport streamable-httpExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)这不是 MCP 错误而是 anyio 的包装噪音你真正的错误在被粘贴内容的最后一行。Client.__aenter__会启动一个任务组task group而 anyio 会把任何从任务组逃逸出的异常都包裹进ExceptionGroup。因此任何从async with Client(...)块逃逸出的异常无论是什么最终都会出现在一个ExceptionGroup里面async def main() - None: async with Client(http://localhost:8000/mcp) as client: await client.read_resource(weather://Atlantis) Exception Group Traceback (most recent call last): | ... | ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception) ----------------- 1 ---------------- | Exception Group Traceback (most recent call last): | ... | ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception) ----------------- 1 ---------------- | Traceback (most recent call last): | ... | mcp.shared.exceptions.MCPError: No forecast for Atlantis. ------------------------------------处理它只需两步看最底部。MCPError: No forecast for Atlantis.才是真正的失败点用它的文本到本文中查找对应条目。在块内捕获。ExceptionGroup只在异常离开async with时出现如果在块内捕获同一个失败就是赤裸裸的MCPError没有任何包装async def main() - None: async with Client(http://localhost:8000/mcp) as client: try: await client.read_resource(weather://Atlantis) except MCPError as e: print(e) # No forecast for Atlantis.[!TIP] 如果失败发生在连接阶段URL 写错、服务器未启动、下文中的421异常是从async with本身逃逸的不存在块内可供捕获。这类情况直接读ExceptionGroup的最底部即可。RuntimeError: Client must be used within an async context managerClient(...)只是构造对象。在进入async with之前没有任何连接建立所以所有方法都会拒绝执行async def main() - None: client Client(http://localhost:8000/mcp) tools await client.list_tools() # RuntimeError进入上下文即可。__aenter__就是连接动作async def main() - None: async with Client(http://localhost:8000/mcp) as client: tools await client.list_tools()__aexit__就是断开动作——这也是为什么 SDK 里不存在client.close()需要你记得调用。测试指南正是建立在这个模式之上。Error executing tool name: message、Error executing tool name与Unknown tool: name你读到的是一份结果result不是异常。call_tool对失败的工具有不会抛出任何异常的约定。对服务器不认识的 city 调用forecast工具抛出的ToolError会随着请求以成功的状态返回result.is_error # True result.content # [TextContent(textError executing tool forecast: No forecast for Atlantis.)] result.structured_content # NoneUnknown tool: get_forecast对服务器从未注册过的名字是同一种形态参数错误也会以同样方式在你的函数真正执行之前就按工具的输入 schema 被拒绝。修复点在客户端检查result.is_error。在call_tool外包一层try/except捕获不到任何上述情况因为根本没有异常可捕。这是刻意设计也是本文最值得内化的认知模型发起了这次调用所以模型应当收到这条消息、获得重试机会。错误处理有完整讲解包括确实会抛异常的MCPError路径。而不带消息的简写形式Error executing tool name含义不同它表示工具崩溃了——工具抛出了自己没有预料的异常或其返回值未通过输出 schema且该异常文本不会出现在协议线上。traceback 在服务器日志里级别为ERROR形如Tool name raised an unexpected exception。TypeError: The tool decorator was used incorrectly. Did you forget to call it? Use tool() instead of tool你写的是mcp.tool而不是mcp.tool()。tool()是一个装饰器工厂少了括号Python 会把你的函数当作name参数传进去。mcp.tool # - missing () def forecast(city: str) - str: Todays forecast for one city. return f{city}: Rain.TypeError: The tool decorator was used incorrectly. Did you forget to call it? Use tool() instead of tool补上括号即可。mcp.resource(...)和mcp.prompt()在同样的疏忽下会给出相同的提示。[!NOTE] 该异常在模块导入时就抛出早于任何客户端连接。所以如果宿主把你的服务器显示为启动失败或已断开而不是已连接但零工具多半就是这种形态自己运行python server.py读 traceback 即可确认。类型检查器也能拦住它——函数不是合法的name值。Tool already exists: name两次注册使用了同一个工具名。先注册的生效第二个被静默丢弃服务器日志里这条警告是唯一信号。复现代码见 docs_src/troubleshooting/tutorial002.pyfrom mcp.server import MCPServer mcp MCPServer(Weather) mcp.tool(nameforecast) def forecast_today(city: str) - str: Todays forecast for one city. return f{city}: Rain. mcp.tool(nameforecast) # Same name. This registration is dropped. def forecast_hourly(city: str, hours: int) - str: The next few hours for one city. return f{city}: Rain for {hours}h.WARNING mcp.server.mcpserver.tools.tool_manager: Tool already exists: forecasttools/list只会报告一个forecast而且它是forecast_today。重命名其中一个即可。这条警告在源码里由工具管理器发出见 src/mcp/server/mcpserver/tools/tool_manager.py 中的logger.warning(fTool already exists: {tool.name})。MCPServer(..., warn_on_duplicate_toolsFalse)可以静默该警告但不会改变结果所以建议保持默认开启。资源和提示词遵循相同规则、输出相同形态的日志行Resource already exists:、Prompt already exists:。我的宿主列出了零个工具这个问题没有对应的错误字符串正因为如此才难以检索。SDK 绝不会把已注册的工具从tools/list中移除所以请由内向外逐一排查服务器到底启动了吗mcp.tool缺括号会在导入期抛异常而在某些宿主里崩溃的服务器看起来和空服务器几乎一样。自己运行python server.py确认。工具是否在宿主实际运行的那个mcp对象上另一个模块里的第二个MCPServer(...)是一台完全不同、且为空的服务器。检查宿主的命令真正 import 的是哪个对象。是否有两个工具重名那么其中之一已经消失。在服务器日志里找Tool already exists:。宿主的列表是否过期启动之后新增的工具只能到达那些处理notifications/tools/list_changed通知的客户端。重启宿主是最直接的笨办法。是否有东西在分流窗口之外写入了stdout服务期间SDK 会把已 flush的游离 stdout 尽量分流到 stderr尽力而为若环境替换了标准流则原样放行但更早 flush 到 stdout 的输出包装脚本的 echo、无缓冲进程里导入期的print()或解释器退出时被排空的缓冲print()都会落进协议流——哪怕只有一行垃圾也可能让宿主断开连接某些宿主便把它渲染成一个什么都没有的服务器。请改用logging模块记录日志。宿主侧其余检查清单见连接到真实宿主。注意非法的工具名不在此列——不合规的名字只会记一条警告工具照样注册、照样列出。MCPError: Server returned an error response服务器硬生生拒绝了 HTTP 请求且响应体不是 JSON-RPC所以 Python 的Client只能给你这个通用占位消息。最常见的成因是刚部署的 Streamable HTTP 服务器。streamable_http_app()以及mcp.run(streamable-http)在未指定transport_security时默认开启DNS rebinding 防护只接受Host头为 localhost 的请求。这在笔记本上是正确默认值在真实域名后面就是错误默认值坏示例见 docs_src/troubleshooting/tutorial003.pyfrom mcp.server import MCPServer mcp MCPServer(Weather) mcp.tool() def forecast(city: str) - str: Todays forecast for one city. return f{city}: Rain. app mcp.streamable_http_app()按这样部署后客户端指向它连接会在握手阶段失败async with Client(https://mcp.example.com/mcp) as client: ...mcp.shared.exceptions.MCPError: Server returned an error response服务器实际发回的字眼421与Invalid Host header永远到不了你面前421 的响应体没有Content-Type: application/json客户端无法解析。它们躺在服务器日志里下一步就该去看它WARNING mcp.server.transport_security: Invalid Host header: mcp.example.com修复方式是transport_security把真正对外服务的域名加入白名单见 docs_src/troubleshooting/tutorial004.pyfrom mcp.server import MCPServer from mcp.server.transport_security import TransportSecuritySettings mcp MCPServer(Weather) mcp.tool() def forecast(city: str) - str: Todays forecast for one city. return f{city}: Rain. app mcp.streamable_http_app( transport_securityTransportSecuritySettings( allowed_hosts[mcp.example.com, mcp.example.com:*], allowed_origins[https://app.example.com], ) )[!IMPORTANT] 这就是全部改动。同一个客户端现在可以连上、协商出2026-07-28协议版本并成功调用forecast。部署与扩容解释了每个字段的含义、反向代理场景以及部署时会变化的其他一切。紧接着的421 Misdirected Request/Invalid Host header就是从另一侧看到的同一个失败。421 Misdirected Request/Invalid Host header这是Server returned an error response在非 Python Client一侧的呈现curl、浏览器网络面板、反向代理访问日志或其他 SDK。curl -i https://mcp.example.com/mcp \ -H Content-Type: application/json \ -H Accept: application/json, text/event-stream \ -d {jsonrpc:2.0,id:1,method:initialize,params:{protocolVersion:2025-06-18,capabilities:{},clientInfo:{name:curl,version:1}}}HTTP/1.1 421 Misdirected Request Invalid Host header421 Misdirected Request是 HTTP 对这个状态码自带的 reason phraseInvalid Host header是 SDK 的响应体PythonClient则把同一事件渲染为Server returned an error response。三者是同一次拒绝。校验针对的是请求携带的Host头而不是服务器绑定的地址所以一个转发公共域名的反向代理会与直接客户端一样触发它。修复方式与上文Server returned an error response里展示的相同transport_securityTransportSecuritySettings(allowed_hosts[...], allowed_origins[...])。其中两个边界细节值得点名allowed_hosts的条目是精确字符串。mcp.example.com匹配不带端口的Host头mcp.example.com:*匹配任何显式端口。两个都写上。响应403、响应体为Invalid Origin header的是对Origin头的兄弟校验。它只会在浏览器场景触发其他客户端不会发送Originallowed_origins是它的白名单。部署与扩容有完整论述包括何时关闭该校验才是诚实的配置。RuntimeError: Task group is not initialized. Make sure to use run().你的 MCP app 被挂载进了另一个 ASGI app而没有任何东西启动它的会话管理器session manager。mcp.streamable_http_app()返回一个 Starlette app其自身 lifespan 会启动会话管理器uvicorn server:app会替你执行这个 lifespan。但Starlette 从不执行被挂载子应用的 lifespan因此一旦 app 进了Mount管理器就永远不启动第一个请求当场爆炸坏示例见 docs_src/troubleshooting/tutorial005.pyfrom starlette.applications import Starlette from starlette.routing import Mount from mcp.server import MCPServer mcp MCPServer(Weather) mcp.tool() def forecast(city: str) - str: Todays forecast for one city. return f{city}: Rain. # The mount works. The MCP apps own lifespan never runs. app Starlette(routes[Mount(/, appmcp.streamable_http_app())])服务器能启动、路由能解析然后uvicorn对每个请求打印ERROR: Exception in ASGI application Traceback (most recent call last): ... RuntimeError: Task group is not initialized. Make sure to use run().客户端看到的是 500。修复方式是在宿主app 上写一个 lifespan进入mcp.session_manager.run()asynccontextmanager async def lifespan(app: Starlette) - AsyncIterator[None]: async with mcp.session_manager.run(): yield app Starlette(routes[Mount(/, appmcp.streamable_http_app())], lifespanlifespan)添加到现有应用是这一主题的专页涵盖单 app 内多服务器与 FastAPI 场景。同类的两条相邻字符串StreamableHTTPSessionManager .run() can only be called once per instance. Create a new instance if you need to run again.—— 管理器是一次性的同一 app 的 lifespan 进入两次就会触发。mcp.session_manager只在调用streamable_http_app()之后才存在所以要先构造路由且只在 lifespan 内部触碰管理器。MCPError: Session not found服务器不认你的客户端发送的Mcp-Session-Id。要么服务器重启过或请求被路由到了另一实例要么会话因为session_idle_timeout期间没有任何在途请求而过期——该超时默认 30 分钟。参见会话生命周期与限制。会话只存活于那一个进程的内存里。这里没有服务器 bug 可找。HTTP 响应是404且其响应体是JSON-RPC所以与上面的421不同PythonClient会原样展示它{jsonrpc: 2.0, id: null, error: {code: -32600, message: Session not found}}修复方式就是重连退出async with Client(...)块再进入一个新的块它会协商出全新会话。对长生命周期客户端而言这意味着在调用周围捕获MCPError遇到这条消息就重连而不是在死会话里反复重试。如果没有重启、客户端也没沉默那么久那就是你在没有 sticky sessions 的情况下运行了多个 worker每个 worker 维护自己的会话表被路由到错误 worker 的请求就会落在这里。部署与扩容与服务旧版客户端讲了全部细节和两种解法sticky 路由或stateless_httpTrue。对服务器运维者来说对应的日志行是Rejected request with unknown or expired session ID: id记录级别是INFO所以在常见的WARNING阈值下不可见。刚部署完看到它成批出现是正常的——所有已连接的客户端都在重连。如果是会话过期该行之前会先出现Session id idle timeout同样为INFO级别。MCPError: Method not found一方发送了另一方没有 handler 的 JSON-RPC 请求e.error.data会指出该方法的名称。常见成因是代际era不匹配某个方法只存在于一个协议修订版却发给了讲另一版协议的对方——比如2025代的resources/subscribe到达2026-07-28连接或2026独有的subscriptions/listen被一个固定在modelegacy的客户端发出。协议版本是哪一方讲什么的地图另一种合理成因从未注册 handler 的可选能力见自动补全。有一样东西不会产生此错误尽管它确实是现代协议移除的请求在2026-07-28连接上调用ctx.elicit()的工具。服务器会拒绝发送该请求所以你得到的其实是下文中的Cannot send elicitation/create: ...。MCPError: Client did not declare the form elicitation capability required by resolver name你的服务器想向用户提问而这个客户端从未声明自己可以被提问。这家 Bistro 在预订前通过一个 resolver 提问见 docs_src/troubleshooting/tutorial007.pyfrom typing import Annotated from pydantic import BaseModel from mcp.server import MCPServer from mcp.server.mcpserver import Elicit, Resolve mcp MCPServer(Bistro) class Confirmation(BaseModel): confirm: bool async def ask_to_confirm(date: str) - Elicit[Confirmation]: Resolver: ask the user to confirm the booking. return Elicit(fBook a table for {date}?, Confirmation) mcp.tool() async def book_table(date: str, answer: Annotated[Confirmation, Resolve(ask_to_confirm)]) - str: Book a table at the bistro. if answer.confirm: return fBooked for {date}. return No booking made.用它替换 Weather 服务器再从一个没有传elicitation_callback的客户端调用book_table。resolver 会在入口处直接拒绝因为连上的客户端从未声明表单式 elicit 能力e.error.data会精确指出缺了什么{ code: -32021, message: Client did not declare the form elicitation capability required by resolver server:ask_to_confirm, data: {requiredCapabilities: {elicitation: {form: {}}}} }给Client(...)传elicitation_callback即可。注册回调本身就是能力声明不存在第二个开关async def main() - None: async with Client(http://localhost:8000/mcp, elicitation_callbackhandle_elicitation) as client: result await client.call_tool(book_table, {date: Friday})客户端回调列出了其余回调sampling_callback、list_roots_callback每一个都以同样方式构成能力声明。[!INFO]-32021是MISSING_REQUIRED_CLIENT_CAPABILITY属于2026-07-28规范新增的三个错误码之一。它们都不是异常类一律以MCPError到达看e.error.code即可mcp.types导出了这些常量。另外两个是-32020HEADER_MISMATCHHTTP 头与它所伴随的请求体不一致和-32022UNSUPPORTED_PROTOCOL_VERSION请求命名的版本此服务器不讲。合规的 SDK 客户端不可能产生其中任何一个所以见到它们请检查你的客户端与服务器之间有什么在改写请求。MCPError: Elicitation not supported与Client did not declare the form elicitation capability ...是同一个缺口只是由那些不做前置检查的路径表达出来服务器需要一个 elicit 被应答而连上的客户端没有注册任何elicitation_callback。你会在ctx.elicit()运行在旧版连接上时见到它也会在任何连接上、从被退回的多轮往返请求中遇到它——只要问题抵达一个没有回调来应答的客户端。修复方式完全一样给Client(...)传elicitation_callback。不存在用户没被问到就作为decline交给你的版本无法被提问的客户端就是一次失败的调用请据此设计你的工具。MCPError: Cannot send elicitation/create: this transport context has no back-channel for server-initiated requests.你的 handler 在请求中途尝试联系客户端而这条连接上承载该调用的通道没有任何能力承载从服务器发起的请求。有三种服务器配置会让一个调用落入这种处境。2026-07-28连接任何传输永远如此。现代协议根本没有服务器发起的请求所以服务器在发送任何东西之前就会拒绝。工具里的ctx.elicit()是撞上它的经典路径——通常就在该工具第一次内存内测试时因为Client(mcp)会在你没要求的情况下协商出2026-07-28。传elicitation_callback不会改变任何东西因为根本不会有请求到达客户端供它应答坏示例见 docs_src/troubleshooting/tutorial006.pyfrom pydantic import BaseModel from mcp.server import MCPServer from mcp.server.mcpserver import Context mcp MCPServer(Bistro) class Confirmation(BaseModel): confirm: bool mcp.tool() async def book_table(date: str, ctx: Context) - str: Book a table at the bistro. result await ctx.elicit(fBook a table for {date}?, schemaConfirmation) if result.action accept and result.data.confirm: return fBooked for {date}. return No booking made.async def test_book_table() - None: async with Client(mcp) as client: await client.call_tool(book_table, {date: Friday})mcp.shared.exceptions.MCPError: Cannot send elicitation/create: this transport context has no back-channel for server-initiated requests.stateless_httpTrue服务器上的旧版连接。无状态意味着每个请求自成一体没有会话、没有服务器到客户端的流因此连拥有这些方法的那一代协议也无处可发elicitation/create或sampling/createMessage、roots/list见 docs_src/troubleshooting/tutorial008.pyfrom pydantic import BaseModel from mcp.server import MCPServer from mcp.server.mcpserver import Context mcp MCPServer(Bistro) class Confirmation(BaseModel): confirm: bool mcp.tool() async def book_table(date: str, ctx: Context) - str: Book a table at the bistro. result await ctx.elicit(fBook a table for {date}?, schemaConfirmation) if result.action accept and result.data.confirm: return fBooked for {date}. return No booking made. # Stateless HTTP: every request is its own world. No channel back to the client. app mcp.streamable_http_app(stateless_httpTrue)json_responseTrue服务器上的旧版连接。POST只用一个 JSON body 应答而一个 body 只能承载响应所以请求中途的ctx.elicit()所需要的请求作用域流在这里同样不存在。会话、它的Mcp-Session-Id和独立流都还在消失的只是请求作用域通道。这条消息会点出它没能发出的方法名。NoBackChannelError是服务器抛出的类但线上只承载底层的MCPError所以上面那句话就是 traceback 的最后一行而不是类名。对2026-07-28客户端三种情况下的修复相同不要在调用中途回连客户端。把提问挪进一个resolver或自己返回一个InputRequiredResult它就变成响应的一部分——而响应是所有连接都能承载的见 docs_src/troubleshooting/tutorial007.py。同一个问题、客户端同一个elicitation_callback区别在内部resolver 让服务器从调用中返回问题而不是推送它因此不会有任何服务器到客户端的内容流动。这能拯救所有2026-07-28客户端无论服务器处于上述三种配置中的哪一种。但旧版客户端不会仅凭改写被拯救2025-11-25没有返回问题的方式所以在旧版连接上 resolver 仍会沿请求作用域通道发送elicitation/create仍需要一个保留该通道的服务器——stateless_httpTrue和json_responseTrue都不行。Elicit 提问覆盖 resolver多轮往返请求覆盖线上发生了什么。[!IMPORTANT] 带ctx.elicit()的工具没有错它只是早于 2026。用modelegacy经典的initialize握手规范2025-11-25及更早连接一个既非stateless_httpTrue也非json_responseTrue的服务器它就能正常工作因为那里存在服务器到客户端的通道。协议版本是每个版本有什么的专页。MCPError: Invalid or expired requestState服务器无法校验你的客户端回传的requestState令牌于是拒绝这一轮。requestState是多轮往返调用在分段之间携带的不透明恢复令牌。MCPServer在发出时对其盖章并校验每一个回传它会在tools/call、prompts/get和resources/read上校验每一个入站request_state——即使 handler 从不铸造令牌也一样。所以一个不是本进程盖章的令牌无论落到哪里都会被拒绝async def main() - None: async with Client(http://localhost:8000/mcp) as client: await client.call_tool(forecast, {city: London}, request_stateround-1-from-worker-a)mcp.shared.exceptions.MCPError: Invalid or expired requestState这条消息是刻意冻结的线上永远不会透露哪项校验失败了。原因会进服务器日志读日志就是全部诊断手段该日志由 src/mcp/server/request_state.py 发出WARNING mcp.server.request_state: requestState rejected on tools/call: malformed你实际会看到的原因unknown key是最关键的一个。默认盖章密钥在进程启动时生成所以落到另一个 worker、负载均衡器后面的另一实例、或重启后的同一服务器的重试其令牌都是用一个本进程从未有过的密钥盖的章。这不是攻击者而是默认值遇上多进程。audience令牌是由服务器名不同的实例盖章的。服务器名是盖章默认的 audience claim所以一个集群必须共享名字或显式设置RequestStateSecurity(audience...)光共享密钥还不够。expired这一轮耗时超过了盖章的ttl——600 秒按轮计不是按调用计。malformed/codec error令牌在传输中被改动或压根不是盖章令牌。request binding令牌随不同的工具、不同的参数或不同的方法回来了。多进程的修复是一个参数所有实例使用相同的keys加一个根本不是参数的东西相同的服务器名或显式共享的audience。mcp MCPServer(Weather, request_state_securityRequestStateSecurity(keys[key]))keys[0]负责盖章列表中的每个密钥都能校验——这正是无停机轮换得以实现的原因。多轮往返请求之保护 requestState 解释印章保护什么与轮换顺序部署与扩容完整走一遍两个 worker 的失败及两段式修复。[!TIP]keys[...]会立即拒绝弱密钥报错消息出奇地有用ValueError: request-state keys must be at least 32 bytes of secret randomness; keys[0] is 7 bytes. Generate one with: python -c import secrets; print(secrets.token_hex(32))照它说的做。仍然没解决如果 SDK 产出的某条消息不在本文页面上那本身就是值得单独上报的文档 bug。在仓库的 issue 跟踪器中搜索大多数错误字符串出现时往往已经有人写好了记录。还是没找到带上完整 traceback 开一个 issue或在 MCP Contributors 的#python-sdk-dev频道提问。速查小结ExceptionGroup: unhandled errors in a TaskGroup从来不是真正的错误。读最后一行在async with Client(...)块内部捕获MCPError可以完全跳过包装。call_tool对失败的工具有不会抛异常的约定。Error executing tool ...和Unknown tool: ...是结果检查result.is_error。工具名后没有消息意味着它崩溃了traceback 在服务器日志里。Client must be used within an async context manager→ 使用async with。Use tool() instead of tool→ 补上括号。服务器日志里的Tool already exists:是两个同名工具合并成一个的唯一信号。一个 421三种写法Server returned an error responsePythonClient、421 Misdirected Request/Invalid Host header其他一切、Invalid Host header: host服务器日志。修复transport_securityTransportSecuritySettings(allowed_hosts[...])。Task group is not initialized→ 挂载的 app 其宿主 lifespan 从未进入mcp.session_manager.run()。Session not found→ 服务器重启或会话过期session_idle_timeout重连。Cannot send elicitation/create: ... no back-channel ...→ctx.elicit()需要一条服务器到客户端通道2026-07-28连接永远没有stateless_httpTrue移除旧版的json_responseTrue移除请求作用域的。改用 resolver旧版客户端还需要一个保留通道的服务器。它的近邻Method not found是请求了对方协议修订版没有的方法。Client did not declare the form elicitation capability ...与Elicitation not supported→ 客户端缺少elicitation_callback。Invalid or expired requestState在线路上永远不会说明原因服务器日志会unknown key意味着要在 worker 之间共享RequestStateSecurity(keys[...])。赞分享人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载相关推荐探索新范式mysql33/mysql社区生态构建完整的周边工具与插件系统指南探索新范式mysql33/mysql社区生态构建完整的周边工具与插件系统指南 MySQL作为全球最流行的开源数据库之一其生态系统的完善程度直接影响开发者的使人工智能MCP 服务MCP ClientsHCCL 参数一致性校验EI0005故障排查指南从报错定位到根因分析HCCL 参数一致性校验EI0005故障排查指南从报错定位到根因分析本指南围绕 CANN 集合通信库HCCL参数面建链阶段的参数一致性校验机制展开人工智能分布式训练高性能计算通信Ascend用 PostHog MCP 工具调试 LLM Trace从 URL 到根因的完整排查指南用 PostHog MCP 工具调试 LLM Trace从 URL 到根因的完整排查指南 PostHog 将 LLM/AI Agent 的每一次交互捕获为一条数据分析后端前端数据可视化大数据上一篇CANN/cann-bench NLLLoss算子下一篇FastAPI 严格 Content-Type 校验默认的 CSRF 防护机制与 strict_content_type 配置详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

MCP Python SDK 排错指南：从 traceback 最后一行到根因的逐一排查

相关推荐

如何把自己的QQ空间历史说说备份到本地：GetQzonehistory使用教程

分时图做T实战：MACD背离与量价协同的日内仓位管理

指向任意 UI 元素即拿到源码位置：React Grab 完整上手教程与排查清单

更多资讯

Pandoc `four_space_rule` 扩展解析：plain 输出如何恢复 pandoc 2.0 的四空格列表缩进

Hugo 模板指南：深入解析 time.Time.Hour 方法（含时区语义与实战示例）

2026年AI编程工具版图：从补全代码到数字员工的五大阵营解析

夸克网盘下载限速怎么破？在线解析与直链提取提速方案详解

LibreChat自托管部署实战：多模型AI对话中台配置与问题排查

SQL注入靶场实战：从报错注入到盲注的核心思路

今日更新

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本周精选

深入解析Transformer多头注意力机制与工程优化

OpenClaw 的 Skills 跑学习任务，模型通道改到 TaoToken 通道行不行？

ChatGPT报错Oops, an error occurred! 全链路排查指南

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？