MCP 工具

CowAgent 支持 Model Context Protocol (MCP)，让 Agent 能够直接调用社区中数以万计的 MCP 工具。配置一次 mcp.json，工具就会以与内置工具完全相同的方式呈现给 LLM，可被自动选择和调用。

Web / 桌面控制台

Web 控制台和桌面客户端「能力」页面的 MCP 工具 区域可以直接添加、编辑、停用和删除 MCP 服务，不必再手工改 mcp.json。

表单或 JSON：支持表单填写，或在 JSON 模式下粘贴标准 mcpServers 配置（可同时包含多个服务），例如 {"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}。
连接测试：检测服务是否可用并列出其工具。保存前会自动检测，未通过时可修改配置或选择「仍然保存」（适用于保存后才能授权的服务）。
配置存储：写入当前 Agent 的 mcp.json，格式与 Claude Desktop / Cursor 一致。
即时生效：修改在下一条消息生效，无需重启。

stdio、SSE、streamable HTTP 都支持。停用的服务器会留在文件里，但不会被拉起。

配置文件

CowAgent 读取 ~/cow/mcp.json。文件不存在时不会启用任何 MCP 工具，也不会报错。 Docker 部署时，官方 docker-compose.yml 已经把宿主机 ./cow 挂载到容器内 /home/agent/cow（即容器用户的 ~/cow），把 mcp.json 放进宿主机 ./cow/ 目录即可生效。

标准格式

完全兼容 MCP 社区标准，同 Claude Desktop / Cursor 一致：

{
  "mcpServers": {
    "<server-name>": {
      "command": "npx",
      "args": ["-y", "some-mcp-package"],
      "env": {
        "API_KEY": "your-key-here"
      }
    }
  }
}

字段	必填	说明
`command`	stdio	启动 server 的可执行命令（如 `npx`、`python`、`uvx`）
`args`	否	传给 command 的参数列表
`env`	否	子进程的环境变量，常用于 API Key
`url`	SSE / Streamable HTTP	远程端点 URL（与 `command` 二选一）
`type`	远程	远程传输类型，可选 `sse` 或 `streamable-http`，默认 `sse`
`headers`	否	远程请求附加 HTTP 头（如 `Authorization`），仅 Streamable HTTP 使用
`scope`	否	OAuth 授权范围，仅需要 OAuth 授权的远程 server 使用（可选）
`disabled`	否	`true` 时跳过该 server，便于临时关闭

完整示例

{
  "mcpServers": {
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

fetch：通用网页抓取，返回页面文本内容，无需 API Key
github：访问 GitHub 仓库、Issue、PR 等，需要 Personal Access Token

Streamable HTTP + Bearer 密钥

远程 server 若使用固定 API Key 认证，需显式指定 type（远程 URL 不指定时会按 sse 处理），并在 headers 中传入密钥：

{
  "mcpServers": {
    "my-remote-tools": {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

header 的值按字面量发送，${API_KEY} 不会从环境变量展开
密钥在 mcp.json 中是明文存储，注意不要提交到版本库
配置了 Authorization 即视为静态认证，不会触发下方的 OAuth 流程，即使密钥是错的

让 Agent 帮你配置

CowAgent 自带 read / write / edit 工具，**直接把要装的 MCP 配置发给 Agent，让它写到配置文件中：例如：

帮我把这个 MCP 加到 ~/cow/mcp.json 里：

{"mcpServers":{"fetch":{"command":"uvx","args":["mcp-server-fetch"]}}}

Agent 会：

访问 MCP 配置文件，合并新 server 配置，保留已有项
自动重载增量的 MCP Server，下一次对话即可使用相应 Tools

mcp.json 中配置的命令会以 Agent 进程的权限启动，因此只有全部可访问权限的会话才允许 Agent 修改 mcp.json；只读和工作区可写会话会拒绝，可切换会话权限，或直接在控制台中添加。

网页授权（OAuth）

部分远程 MCP需要 OAuth 网页授权，直接配置会返回 401。CowAgent 内置标准 OAuth 流程，无需手填 token，正常配置即可，例如：

{
  "mcpServers": {
    "xmind": {
      "type": "streamable-http",
      "url": "https://app.xmind.com/api/mcp"
    }
  }
}

server 首次加载遇到 401 时会自动发起授权：本机运行会自动打开浏览器，服务器部署则把授权链接打印到日志，复制到浏览器打开。授权同意后即完成，该 server 随即上线，令牌过期自动刷新，无需重复授权。

依赖 Web 服务：授权回调由 Web 控制台（默认端口 9899）接收，需保证 Web channel 正在运行。
凭证存储：令牌持久化在 ~/.cow/mcp_oauth.json，重启后复用。
回调地址：默认 http://127.0.0.1:9899/mcp/oauth/callback；若部署在服务器、授权浏览器在另一台设备，在 config.json 设置 mcp_oauth_redirect_base（如 http://你的IP:9899）即可。

工作方式

启动时异步加载：mcp.json 中配置的所有 server 会在后台异步加载，不阻塞主流程，对话可以立刻使用
热更新：用户或 Agent 修改 mcp.json 后，消息处理完成时会自动重载变更的 server，无需重启 cow
平铺呈现：每个 MCP server 暴露的多个方法会平铺为独立的工具，LLM 直接选择调用，不需要二次决策

支持的传输协议

协议	说明	配置字段
stdio	子进程通信，最常见，社区生态最丰富	`command` + `args`
SSE	HTTP Server-Sent Events，旧版远程协议	`url`（默认）
Streamable HTTP	新版远程协议，单端点收发，逐步取代 SSE	`type: "streamable-http"` + `url`

排错

现象	排查方向
启动后 Agent 没有 MCP 工具	检查 `~/cow/mcp.json` 是否存在、JSON 格式是否合法
某个 server 加载失败	查看启动日志中的 `[MCP] Server 'xxx' load failed`，常见为依赖未装、API Key 缺失
修改 `mcp.json` 没有生效	改动会在下一条消息生效；若 server 配置不变（如只改注释），不会触发重启
Docker 部署	确认宿主机 `./cow` 已挂载到容器内 `/home/agent/cow`，`mcp.json` 直接放进宿主机 `./cow/` 目录即可，或者直接对话 Agent 安装

MCP 市场推荐

可以从各个第三方广场寻找现成的 MCP server，复制 JSON 配置即可使用，例如：

mcp.so — 全球 MCP 服务索引
ModelScope MCP 广场 — 魔搭社区 MCP 广场，国内访问更稳定

只要遵循 MCP 标准协议（stdio / SSE / Streamable HTTP），都可以直接接入 CowAgent。

工具系统

内置工具

可选工具

MCP 工具

Web / 桌面控制台

配置文件

标准格式

完整示例

Streamable HTTP + Bearer 密钥

让 Agent 帮你配置

网页授权（OAuth）

工作方式

支持的传输协议

排错

MCP 市场推荐

​Web / 桌面控制台

​配置文件

​标准格式

​完整示例

​Streamable HTTP + Bearer 密钥

​让 Agent 帮你配置

​网页授权（OAuth）

​工作方式

​支持的传输协议

​排错

​MCP 市场推荐

Web / 桌面控制台

配置文件

标准格式

完整示例

Streamable HTTP + Bearer 密钥

让 Agent 帮你配置

网页授权（OAuth）

工作方式

支持的传输协议

排错

MCP 市场推荐