错误处理

工具失败有两种方式，SDK 对它们的处理截然不同。

抛出普通异常，看到它的是模型。抛出 MCPError，看到它的是协议。

这一页讲的就是怎么选。

模型能纠正的错误

拿一个查东西的工具来说，让它查不到：

from mcp.server import MCPServer

mcp = MCPServer("Bookshop")

CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}


@mcp.tool()
def get_author(title: str) -> str:
    """Look up the author of a book in the catalog."""
    if title not in CATALOG:
        raise ValueError(f"No book titled {title!r} in the catalog.")
    return CATALOG[title]

这两行没有任何 MCP 特有的东西。get_author 抛出一个普通的 ValueError，和任何 Python 函数一样。

用一个书目里没有的书名去调用它，看看结果：

result.is_error            # True
result.content             # [TextContent(text="Error executing tool get_author: No book titled 'Nothing' in the catalog.")]
result.structured_content  # None

• 请求成功了。有一个结果；调用方这边什么也没抛出。
• is_error 为 True，你的异常消息（前面加了工具名）就在 content 里，正是模型读取的位置。
• structured_content 为 None。失败的调用没有返回值可供结构化。

这就是工具错误，也是工具抛出的任何异常的默认归宿。而且它几乎总是你想要的效果。

调用工具的是模型，参数也是它挑的。所以工具错误就是对话里的一个回合：模型读到“No book titled 'Nothing' in the catalog.”，发现自己猜错了书名，就换个更好的再调一次。你只写了一个 raise，就得到了一个会自我纠正的智能体。

模型纠正不了的错误

现在把 ValueError 换成 MCPError。

from mcp import MCPError
from mcp.server import MCPServer
from mcp.types import INVALID_PARAMS

mcp = MCPServer("Bookshop")

CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}


@mcp.tool()
def get_author(title: str) -> str:
    """Look up the author of a book in the catalog."""
    if title not in CATALOG:
        raise MCPError(code=INVALID_PARAMS, message=f"No book titled {title!r} in the catalog.")
    return CATALOG[title]

MCPError 是 SDK 的协议错误。它是工具包装层唯一不捕获的异常：它会向上传播，整个 tools/call 请求以一个 JSON-RPC 错误失败，而不是返回结果。

{
  "code": -32602,
  "message": "No book titled 'Nothing' in the catalog."
}

• 没有结果。没有 content，没有 is_error：模型没有任何东西可读。
• 收到这个错误的是宿主应用，和工具根本不存在时的情形一样。
• code、message 和 data 原封不动地送达。INVALID_PARAMS 就是 -32602；mcp.types 把它和其他 JSON-RPC 错误码（INVALID_REQUEST、INTERNAL_ERROR……）作为常量导出，这样你永远不用手写魔法数字。

mcp.shared.exceptions.MCPError: No book titled 'Nothing' in the catalog.

该抛哪一个

两条路径回答的是两个不同的问题。

• 抛出任意异常，对应执行层面的失败：工具想做的事没做成。调用是模型选的，所以后果也该让模型看到，给它补救的机会。拼错的书名、超时的上游 API、不存在的数据行：全是工具错误。
• 抛出 MCPError，对应请求本身就该被拒绝的情况：客户端缺少工具所依赖的某项能力，服务器当前的状态没法为任何人服务，调用方跳过了某个必需步骤。这些问题模型怎么重试都修不好，所以把消息交给它没有任何好处。

一个问题就能定夺：换个更聪明的模型，能避免这个问题吗？ 能 -> 普通异常。不能 -> MCPError。

按这个标准，第二版 get_author 选错了：换个更好的书名就能解决，所以模型理应看到那条消息。它放在这里是为了让你看清机制，而不是推荐这种写法。

不存在的资源

资源也划出同样的界线，并为常见情况自带了一个具名异常。

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ResourceNotFoundError

mcp = MCPServer("Bookshop")

CATALOG = {"Dune": "Frank Herbert", "Neuromancer": "William Gibson"}


@mcp.resource("books://{title}")
def book(title: str) -> str:
    """The catalog entry for one book."""
    if title not in CATALOG:
        raise ResourceNotFoundError(f"No book titled {title!r} in the catalog.")
    return f"{title} by {CATALOG[title]}"

books://{title} 是一个模板。它能匹配任何书名，所以“URI 格式正确”和“这本书存在”是两个不同的问题，而第二个只有你的函数能回答。

答案为否时，抛出 ResourceNotFoundError。SDK 会把它转成规范为缺失资源指定的那个协议错误：-32602，请求的 URI 放在 data 里，让客户端知道失败的是哪一次读取。

{
  "code": -32602,
  "message": "No book titled 'Nothing' in the catalog.",
  "data": {"uri": "books://Nothing"}
}

注意这里没有 is_error=True 式的“半个结果”。资源读取要么返回内容，要么失败：资源只有协议这一条路径。模板以及资源的其他方方面面，详见 资源。

你永远不用抛的错误

不合法的参数根本到不了你的函数。

给 get_author 传一个不是字符串的 title，SDK 会在调用你之前就对照输入模式把它拒掉，得到的同样是模型能读懂并改正的那种 is_error=True 工具错误。工具 用一个 Field(le=50) 约束演示了同样的拒绝。

这意味着有一整类 raise 语句不用你写：不要重复校验自己的类型注解。

回顾

• 在工具里抛出任意异常 -> 调用返回 is_error=True，你的消息在 content 里。模型读到后可以重试。这是默认行为。
• 抛出 MCPError -> 调用本身以 JSON-RPC 错误失败。模型什么也看不到；由宿主处理。code、message 和 data 原封不动地保留。
• 决定性的问题：“换个更聪明的模型，能避免这个问题吗？”能 -> 异常。不能 -> MCPError。
• 资源处理函数抛出 ResourceNotFoundError -> 协议的 -32602，URI 在 data 里。
• 不合法的参数在你的函数运行之前就会对照模式被拒掉；这些不用你 raise。
• from mcp import MCPError；错误码常量来自 mcp.types。

错误处理完毕。服务器对外暴露的内容就是这些。每个处理函数在运行期间能读到什么、又能反过来对客户端做什么，是下一部分的内容：在处理函数内部。

你最有可能碰到的那些 SDK 错误的原文、各自的含义，以及每个错误一步到位的修复方法，详见 故障排查。