为MCP工具建立稳定错误契约

目标

让MCP客户端能据错误类型采取安全且可预期的下一步。

步骤

1. 列出工具可能遇到的参数错误、权限拒绝、依赖不可用和未知异常。 [mcp-errors] [mcp-tools]
2. 对模型可纠正的查询失败抛 ToolError；对client必须处理的协议拒绝抛 MCPError(code, message, data)。 [mcp-errors] [mcp-tools]
3. 不要return错误字符串；异常工具错误需检查 CallToolResult.is_error，未知崩溃细节留在服务端日志。 [mcp-errors] [mcp-tools]
4. 服务端记录受控诊断ID，将完整内部异常留在受保护日志中。 [mcp-errors] [mcp-tools]
5. 注入各类故障并验证客户端响应、重试行为及日志脱敏。 [mcp-errors] [mcp-tools]

验证方式

每类错误都有可预测响应；堆栈、令牌和连接信息不会出现在客户端响应或普通日志。

故障处理

若错误泄露内部细节，收紧异常映射，并将受保护服务端日志与客户端错误分离。