CODEAGENT / MCP

MCP 工具接入

需要新增可执行工具时，让工具在独立服务中运行，再通过 MCP 与 CodeAgent 连接。

选择接入方式

可以在桌面端的连接器配置中按服务说明填写连接地址或本机启动命令。插件清单里的 mcp 贡献目前使用直接启动的 stdio 服务。

下面的模板演示本机 Node 服务；服务程序和 Node.js 必须已经安装。下载模板并不会安装或生成一个 MCP 服务。

声明本机服务

MCP plugin.json

{
  "manifestVersion": 1,
  "id": "local-tools",
  "name": "本地 MCP 工具",
  "version": "1.0.0",
  "permissions": [
    "mcp.start"
  ],
  "mcp": [
    {
      "id": "tools",
      "name": "本地工具服务",
      "command": "node",
      "args": [
        "C:/tools/my-mcp-server/server.mjs"
      ],
      "permissions": [
        "mcp.start"
      ]
    }
  ]
}

下载模板，把 args 中的路径替换成你的真实服务入口。command 是可执行程序，args 是参数数组；不要把整条 shell 命令写进 command。

需要环境变量时

在 mcp 条目中加入 environment 描述符，让用户在插件页面配置实际凭据：

environment 字段示例

[
  {
    "name": "SERVICE_API_KEY",
    "label": "服务 API Key",
    "required": true,
    "secret": true
  }
]

这里只描述变量，不包含 value 字段。不需要凭据的服务可以省略 environment。

确认工具真的可以调用

按服务自身说明启动并验证其 MCP 协议；stdio 的标准输出应只输出协议消息，诊断日志写入标准错误。
在 CodeAgent 配置服务或导入插件，审查并启用，补齐必要凭据。
检查连接状态和可用工具列表。
发送明确需要该工具的任务，在会话中检查工具请求、审批和返回结果。

服务连接成功不等于所有任务都会自动调用它。工具仍取决于当前会话、模型返回、工具可用性和任务权限。

连接失败的排查顺序

现象	检查
找不到可执行程序	确认 command 程序已安装、桌面端可访问，必要时使用绝对路径。
服务退出或握手失败	检查 args 路径、服务依赖、stdio 协议和标准输出日志。
缺少环境变量	检查插件页面是否已填写所有 required 环境变量。
看不到工具或调用被拒绝	检查连接状态、服务暴露的工具、插件启用状态和当前任务权限。

MCP 官方服务开发文档 →