Claude Code 终端 MCP 与 VS Code 扩展 MCP 的连接差异及配置指南

问题现象

在 MCP for Unity 中设置 Client 为 ClaudeCode 后：

• 终端里运行 claude 命令 → MCP 正常连接，可以使用 Unity 工具
• 使用 Trae / VS Code 的 Claude Code 扩展 → MCP 无法连接，看不到 Unity 工具

根因

终端版 Claude Code 和 VS Code 扩展版是两套独立的进程，两者的 MCP 配置不共享。

• 终端版：从 ~/.claude.json 读取 MCP 服务器配置。MCP for Unity 设置 Client 为 ClaudeCode 时，它会自动写入这个文件的 MCP 配置，所以终端里能用
• VS Code 扩展版：需要项目级的 .mcp.json 文件来注册 MCP 服务器，扩展不会自动读取终端版的配置

解决方案

方法 1：项目级 .mcp.json 配置（推荐）

在 Unity 项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "unity-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  },
  "servers": {
    "unity-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}

说明： mcpServers 是 Claude Code CLI 的标准 key，servers 是 VS Code 扩展的标准 key。同时写两个可以兼容双方。"type": "http" 告诉客户端使用 HTTP 传输协议连接 MCP 服务器（Unity MCP 使用的是 Streamable HTTP）。

配置完成后：

1. Ctrl+Shift+P → Developer: Reload Window 重启 VS Code 窗口
2. 重新打开 Claude Code，检查系统提示中是否出现 unity-mcp 的服务器指令

方法 2：CLI 命令直接注册（备用方案）

如果方法 1 不生效，用 claude mcp add-json 命令将 MCP 服务器注册到全局配置 ~/.claude.json：

claude mcp add-json --scope user unity-mcp '{"type":"http","url":"http://127.0.0.1:8080/mcp"}'

--scope user 表示在所有项目中可用。这个命令写入 ~/.claude.json，VS Code 扩展也会读取这个文件。

执行完后同样需要 Developer: Reload Window。

方法 3：验证连接

重启扩展后，检查以下几个信号确认 MCP 已连接：

1. Claude Code 的系统提示中显示：

   ## unity-mcp
   This server provides tools to interact with the Unity Game Engine Editor.
   

2. 可以正常调用 Unity MCP 的工具，例如 read_console、manage_editor.play 等
3. 在 Unity 的 Window → MCP for Unity 面板中可以看到客户端的连接状态

关键细节

项目	终端版 (CLI)	VS Code 扩展版
配置文件	~/.claude.json	.mcp.json (项目级)
MCP Server key	mcpServers	servers（推荐）
传输类型	自动检测	需要显式指定 "type": "http"
重启方式	重新运行 claude	Developer: Reload Window

常见问题

Q: 为什么终端能用但扩展不行？
A: MCP for Unity 的 ClaudeCode Client 设置会自动写终端版的配置文件（~/.claude.json），但 VS Code 扩展有自己独立的 MCP 注册机制，需要额外的项目级配置。

Q: 配置了 .mcp.json 还是不生效？
A: 试试方法 2（CLI 命令注册），或者检查 Unity 的 MCP 服务器端口是不是 8080（默认是 6401，可以在 MCP for Unity 面板里查看实际端口）。

Q: 两个方法都试了还是不行？
A: 检查 VSCode 的 Output 面板，选择 Claude Code 查看 MCP 连接日志。常见错误包括：

• 端口被占用 → 在 Unity 的 MCP for Unity 面板里换个端口
• 网络权限 → 确保防火墙允许 127.0.0.1:8080 的本地连接

---

环境：Claude Code CLI v2.1.153 + MCP for Unity Server v9.7.1 + Trae (VSCode Fork) + Windows 11