MCP 服务器问题分三类：服务器不启动（路径/权限问题）、工具不出现（配置或协议握手问题）、工具列出但不被调用（描述不清晰或 schema 错误）。调试的关键是先在 SDK 外单独测试服务器，通过 stdin 发 JSON-RPC 请求验证协议是否正确。

GitHub Copilot SDK 调试 MCP 服务器：从启动失败到工具不被调用的完整排查

调试前的基本检查

• MCP 服务器可执行文件存在且有运行权限
• 命令路径正确（不确定时用绝对路径）
• 工具已启用：tools: ["*"] 或具体工具名列表
• 服务器正确响应 initialize 请求
• Windows 上没有防火墙或杀软拦截进程

开启 MCP 调试日志

在 MCP 服务器配置中添加调试环境变量：

mcpServers: {
  'my-server': {
    type: 'local',
    command: '/path/to/server',
    args: [],
    env: {
      MCP_DEBUG: '1',
      DEBUG: '*',
      NODE_DEBUG: 'mcp'  // 针对 Node.js 编写的 MCP 服务器
    }
  }
}

在 SDK 外单独测试 MCP 服务器

原则：先在 SDK 外确认服务器工作正常，再排查 SDK 集成问题。

测试 initialize 握手

# Unix/macOS
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | /path/to/your/mcp-server

预期返回：

{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"your-server","version":"1.0"}}}

测试工具列表

echo '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' | /path/to/your/mcp-server

预期返回包含工具定义的 tools 数组。

常见问题排查

服务器不启动

现象：没有工具出现，日志里也没有错误。

原因	解决方案
命令路径错误	使用绝对路径 /usr/local/bin/server
缺少执行权限	chmod +x /path/to/server
缺少依赖	在终端直接运行命令排查
工作目录问题	在配置中设置 cwd

排查方法：模拟 SDK 会执行的命令，直接在终端运行：

cd /expected/working/dir
/path/to/command arg1 arg2

服务器启动了但工具不出现

现象：服务器进程在运行，但 Copilot 看不到任何工具。

1. 工具未在配置中启用：

mcpServers: {
  'server': {
    // ...
    tools: ['*']  // 必须设置为 "*" 或具体工具名列表
  }
}

2. 服务器未实现 tools/list：用手动测试脚本发 tools/list 请求验证。

3. 初始化握手失败：服务器必须正确响应 initialize，并处理 notifications/initialized 通知。

工具列出但不被调用

现象：工具在调试日志中出现了，但模型不使用它。

Prompt 描述不够明确：

// 不好：太模糊
await session.sendAndWait({ prompt: '今天天气怎么样？' })

// 更好：明确提示使用工具
await session.sendAndWait({ 
  prompt: '请使用 weather 工具获取北京当前的温度' 
})

工具描述不清晰：

// 不好：模型不知道什么时候该用
{ name: 'do_thing', description: '做事情' }

// 好：清楚说明用途和返回值
{ name: 'get_weather', description: '获取指定城市的当前天气，返回温度、湿度和天气状况' }

Schema 问题：确保 inputSchema 是有效的 JSON Schema，required 数组中列出所有必填字段。

超时错误

现象：MCP tool call timed out 错误。

增加工具调用超时：

mcpServers: {
  'slow-server': {
    type: 'local',
    command: '/path/to/server',
    timeout: 60000  // 60 秒（默认 30 秒）
  }
}

如果工具本身耗时长（如调用外部 API），考虑让工具返回"任务已提交"然后提供轮询接口，而不是阻塞等待。

最佳实践

工具描述写给 AI 看：描述要帮助模型理解"什么时候该调用这个工具"、"这个工具能返回什么"，而不是写给人看的函数文档。

始终用绝对路径：不要依赖相对路径或 PATH 环境变量，命令路径写死绝对路径最可靠。

常见问题

Q: SDK 内置的 built-in 工具（read_file 等）和 MCP 工具的优先级是什么？

A: 两者平行存在，都会暴露给模型。如果工具名冲突，MCP 工具会覆盖内置工具。建议给 MCP 工具名加前缀避免冲突，如 myapp_get_user 而不是 get_user。

Q: MCP 服务器进程崩溃了，会影响整个 SDK 吗？

A: 不会影响 SDK 主进程，但该 MCP 服务器的工具都会不可用。onErrorOccurred Hook 会收到相关错误。SDK 目前不会自动重启 MCP 服务器进程，需要应用层监控和重启。

Q: 可以在运行时动态添加 MCP 服务器吗？

A: 目前 MCP 服务器配置在 createSession 时确定，不支持动态添加。需要重新创建 Session 才能更换 MCP 配置。