Munk AI logoMunk AI
安装
返回文档
接入方式

配置 MCP

了解如何把 Munk AI 的 HTTP MCP endpoint 接到 Cursor、Trae 和 Claude Code。

先启动 Munk AI

先运行：

munk serve --host 127.0.0.1 --port 16888

当前可用的 endpoint

Munk AI 会从同一个本地 munk serve 进程里同时暴露两个 HTTP MCP endpoint：

http://127.0.0.1:16888/mcp
http://127.0.0.1:16888/mcp/device
  • /mcp：适合 handoff / orchestration 工作流，例如 doctor、plan_create、verify_change、review、run_plan、runs_list
  • /mcp/device：适合 interactive device control，例如 devices_list、session_start、session_observe、session_act、session_finalize 如果你第一次只准备配一个 MCP server，建议先从 /mcp 开始。

接上之后可以做什么

连通后，Agent 就可以使用你所配置 endpoint 对应的 Munk AI tools：

  • /mcp：planning / review / verification / run inspection
  • /mcp/device：observe / act 式的设备交互控制

Cursor

Cursor 支持通过图形界面和 mcp.json 配置 MCP。

方式 1：项目级配置

在工作区里创建 .cursor/mcp.json：

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

如果你希望团队成员共享同一套本地 Munk AI 接入方式，这是最合适的方案。

如果你还想把 interactive device MCP 一起接进来，可以写成：

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    },
    "munk-device-control": {
      "url": "http://127.0.0.1:16888/mcp/device"
    }
  }
}

方式 2：全局配置

创建 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

如果你希望所有本地项目都能直接复用这套配置，可以用这个方式。

Cursor 里的注意点

  • 如果 MCP server 没有立刻出现，可以重启或 reload Cursor。
  • 使用前先确认 munk serve 还在运行。
  • 如果你同时配置了两个 endpoint，建议用 munk-handoff 和 munk-device-control 这种清晰名字，方便 Agent 区分用途。
  • 如果你希望 Agent 调用工具时少一些确认弹窗，可以再单独配置 Cursor 自己的 tool approval 或 auto-run 设置。

Trae

Trae 支持通过 MCP 设置页面和项目级 JSON 文件配置 MCP。

方式 1：在界面里手动添加

在 Trae 里：

  1. 打开 Settings
  2. 进入 MCP
  3. 点击 Add > Add Manually
  4. 粘贴下面这段 JSON
{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

如果你还想接入 interactive device endpoint，可以改成：

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    },
    "munk-device-control": {
      "url": "http://127.0.0.1:16888/mcp/device"
    }
  }
}

方式 2：项目级配置

在工作区里创建 .trae/mcp.json：

{
  "mcpServers": {
    "munk-handoff": {
      "url": "http://127.0.0.1:16888/mcp"
    }
  }
}

然后在 Settings > MCP 里开启 project MCP。

Trae 里的注意点

  • 开启 project MCP 后，Trae 会自动读取 .trae/mcp.json。
  • 使用前先确认 munk serve 还在运行。
  • 如果你同时配置了两个 endpoint，建议给它们不同的 server 名称，减少工具混用心智。
  • 如果你开启了 Trae 的 MCP auto-run，Agent 会更积极地直接调用这些工具。

Claude Code

Claude Code 可以直接用命令行把 Munk AI 注册进去。

项目级配置

运行：

claude mcp add --scope project --transport http munk-handoff http://127.0.0.1:16888/mcp

如果你还想接入 interactive device MCP，再执行：

claude mcp add --scope project --transport http munk-device-control http://127.0.0.1:16888/mcp/device

用户级配置

运行：

claude mcp add --scope user --transport http munk-handoff http://127.0.0.1:16888/mcp

如有需要，也可以再加：

claude mcp add --scope user --transport http munk-device-control http://127.0.0.1:16888/mcp/device

验证是否生效

运行：

claude mcp list

如果配置成功，你应该能在列表里看到 munk-handoff，如果也加了 device endpoint，还会看到 munk-device-control。

Claude Code 里的注意点

  • 使用前先确认 munk serve 还在运行。
  • 如果后续不再需要，可以运行 claude mcp remove munk-handoff 或 claude mcp remove munk-device-control 删除对应配置。

推荐使用顺序

第一次配置时，推荐直接按这个顺序来：

  1. 先启动 munk serve
  2. 再打开 IDE 或 Claude Code
  3. 让 Agent 通过 MCP 调用 Munk AI

常见排查项

如果 server 没显示出来，或者 tools 不能正常调用，优先检查这些：

  • munk serve 是否还在运行
  • 启动时是否误加了 --disable-mcp
  • MCP URL 是否准确写成 http://127.0.0.1:16888/mcp 或 http://127.0.0.1:16888/mcp/device
  • IDE 是否已经重新加载最新的 MCP 配置
  • Agent 是否已经启用了对应的 MCP tools

下一步建议

连通之后，可以先试几个很小的请求：

  • “用 Munk AI 执行一次 doctor”
  • “列出当前可用的 Munk AI apps”
  • “基于这次代码改动，用 verify_change 生成验证计划”
  • “通过 /mcp/device 启动一个 session，observe 当前界面，然后点击主按钮”

如果你还想从更高层理解 CLI、MCP、GUI 和 Local API 之间怎么分工，可以继续阅读接入方式与主要入口。