调试

​

调试工具概览

1. MCP Inspector：交互式、与传输无关的测试 UI。连接到 stdio 或 Streamable HTTP 服务器，调用工具、提示和资源，并观察通知流。这应当是你的第一站。
2. 服务器日志：结构化日志输出到 stderr（stdio 传输）或通过 OpenTelemetry（所有传输）。自协议版本 2026-07-28 起，通过协议进行的日志记录（notifications/message）已弃用。
3. 客户端开发者工具：大多数 MCP 客户端都暴露日志和连接状态。参见下方在 Claude Desktop 中调试作为一个示例，或查阅你客户端的文档。

​

实现日志记录

​

服务器端日志

import logging

from mcp.server import MCPServer

logger = logging.getLogger(__name__)

mcp = MCPServer("reports")


@mcp.tool()
async def fetch_report(report_id: str) -> str:
    """Fetch a report by id."""
    logger.info("Fetching report %s", report_id)
    return f"Report {report_id} is ready."

await server.sendLoggingMessage({
  level: "info",
  data: "Server started successfully",
});

• 启动步骤
• 资源访问
• 工具执行
• 错误情况
• 性能指标

​

常见问题

​

工作目录

• 通过客户端配置启动的服务器的工作目录可能是未定义的（例如 macOS 上的 /），因为客户端可能从任何位置启动
• 在你的配置和 .env 文件中始终使用绝对路径，以确保可靠运行
• 对于直接通过命令行测试服务器，工作目录将是你运行命令的位置

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/data"
      ]
    }
  }
}

​

环境变量

{
  "mcpServers": {
    "myserver": {
      "command": "mcp-server-myapp",
      "env": {
        "MYAPP_API_KEY": "some_key"
      }
    }
  }
}

​

服务器启动

1. 路径问题
   • 不正确的服务器可执行文件路径
   • 缺少必需的文件
   • 权限问题
   • 尝试为 command 使用绝对路径
2. 配置错误
   • 无效的 JSON 语法
   • 缺少必需的字段
   • 类型不匹配
3. 环境问题
   • 缺少环境变量
   • 不正确的变量值
   • 权限限制

​

连接问题

1. 检查客户端日志
2. 验证服务器进程正在运行
3. 使用 Inspector 独立测试
4. 验证协议兼容性：调用 server/discover 查看服务器支持哪些协议版本。UnsupportedProtocolVersionError（-32022）会在其 data 字段中列出服务器所支持的版本
5. 检查每请求的 _meta 字段：每个请求都必须携带 io.modelcontextprotocol/protocolVersion 和 io.modelcontextprotocol/clientCapabilities，客户端还应包含 io.modelcontextprotocol/clientInfo。缺少任一必需字段的请求会以错误 -32602（Invalid params）被拒绝，许多其他格式错误的输入也返回相同的代码。如果服务器需要一个请求的 clientCapabilities 未声明的能力（例如征询），它会返回一个 MissingRequiredClientCapabilityError（-32021），并指明缺少的能力。检查请求的 _meta 和 server/discover 响应，以验证双方都声明了你所期望的内容

​

在 Claude Desktop 中调试

​

检查服务器状态

​

查看日志

• macOS：~/Library/Logs/Claude
• Windows：%APPDATA%\Claude\logs

tail -n 20 -F ~/Library/Logs/Claude/mcp*.log

type "$env:AppData\Claude\logs\mcp*.log"

• 服务器连接事件
• 配置问题
• 运行时错误
• 消息交换

​

使用 Chrome DevTools

1. 创建一个 developer_settings.json 文件，并将 allowDevTools 设为 true：

echo '{"allowDevTools": true}' > ~/Library/Application\ Support/Claude/developer_settings.json

'{"allowDevTools": true}' | Set-Content "$env:AppData\Claude\developer_settings.json"

2. 打开 DevTools：Command-Option-I（macOS）或 Ctrl+Alt+I（Windows）

• 主内容窗口
• 应用标题栏窗口

• 消息负载
• 连接时序

​

调试工作流

​

开发周期

1. 初始开发
   • 使用 Inspector 进行基本测试
   • 实现核心功能
   • 添加日志记录点
2. 集成测试
   • 在你的目标 MCP 客户端中测试
   • 监控日志
   • 检查错误处理

​

测试变更

• 配置变更：重启 MCP 客户端
• 服务器代码变更：重启客户端（对于 Claude Desktop，完全退出并重新打开；仅关闭窗口是不够的）
• 快速迭代：在开发过程中使用 Inspector

​

最佳实践

​

日志策略

1. 结构化日志
   • 使用一致的格式
   • 包含上下文
   • 添加时间戳
   • 跟踪请求 ID
2. 错误处理
   • 记录堆栈跟踪
   • 包含错误上下文
   • 跟踪错误模式
   • 监控恢复
3. 性能跟踪
   • 记录操作时序
   • 监控资源使用
   • 跟踪消息大小
   • 测量延迟

​

安全考量

1. 敏感数据
   • 净化日志
   • 保护凭据
   • 屏蔽个人信息
2. 访问控制
   • 验证权限
   • 检查身份认证
   • 监控访问模式

​

获取帮助

1. 第一步
   • 检查服务器日志
   • 使用 Inspector 测试
   • 审查配置
   • 验证环境
2. 支持渠道
   • GitHub issues
   • GitHub discussions
3. 提供信息
   • 日志摘录
   • 配置文件
   • 复现步骤
   • 环境详情

​

后续步骤