# MCP 服务器

通过 OAuth 或个人访问令牌，将 Claude、ChatGPT、Cursor、VS Code、Codex 或任何 MCP 客户端连接到 Beeuni。一个 URL 即可访问你能打开的所有项目。无需安装任何东西。

Canonical page: https://beeuni.ai/docs/zh/connect/mcp

> **实验性功能。** 其工具可能会在没有弃用通知的情况下发生变化。

Beeuni 提供一个托管的 MCP 服务器：

```text
https://api.beeuni.ai/v1/mcp
```

只需将此 URL 添加到 MCP 客户端一次。首次调用时，客户端会提示你在浏览器中登录 Beeuni。之后，客户端便会以你的身份，使用你的权限，访问你能打开的所有账户和项目——与 [CLI](/docs/zh/cli) 的访问范围相同。URL 中不包含项目名称：工具会接收 `project_id` 或 `session_id`，而 `list_projects` 会列出它们。无需安装任何东西。

<a id="add-it-to-a-client"></a>

## 添加到客户端

除非步骤中指定使用令牌，否则以下客户端都会在首次使用时通过 OAuth 登录。无需替换任何内容：所有项目使用相同的 URL。

### Claude Code

```bash
claude mcp add --transport http beeuni https://api.beeuni.ai/v1/mcp
```

在 Claude Code 中运行 `/mcp` 并登录。若要改用个人访问令牌，请在命令中添加 `--header "Authorization: Bearer $BEEUNI_TOKEN"`。

<a id="claude-desktop-and-claudeai"></a>

### Claude Desktop 和 claude.ai

**设置 → 连接器 → 添加自定义连接器**。粘贴 URL 并登录。

### ChatGPT

自定义 MCP 连接器需要开发者模式。根据 OpenAI 的[开发者模式指南](https://developers.openai.com/api/docs/guides/developer-mode)，在**设置 → 安全与登录**中启用**开发者模式**，然后从 ChatGPT 插件页面（加号按钮）创建一个开发者模式应用。输入 URL 并选择 **OAuth** 身份验证。OpenAI 会列出适用的方案和菜单名称，这些内容可能会变动；如果标签名称不同，请参阅该指南。

### Cursor

使用 **Connect MCP** 中的 **Add to Cursor** 按钮，或将服务器添加到 `~/.cursor/mcp.json`（所有项目）或 `.cursor/mcp.json`（单个项目）：

```json
{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp" } } }
```

### VS Code

将服务器添加到 `.vscode/mcp.json`。VS Code 使用 `servers`，而不是 `mcpServers`，并且需要 `type`：

```json
{ "servers": { "beeuni": { "type": "http", "url": "https://api.beeuni.ai/v1/mcp" } } }
```

### Codex

```bash
codex mcp add beeuni --url https://api.beeuni.ai/v1/mcp
codex mcp login beeuni
```

或者编辑 `~/.codex/config.toml`。若要使用个人访问令牌，请指定保存该令牌的环境变量名称：

```toml
[mcp_servers.beeuni]
url = "https://api.beeuni.ai/v1/mcp"
bearer_token_env_var = "BEEUNI_TOKEN"
```

<a id="other-clients"></a>

### 其他客户端

添加一个使用此 URL 的远程（Streamable HTTP）MCP 服务器。无法运行 OAuth 的客户端会将个人访问令牌作为标头发送（见下文）。

打开工作区菜单（左上角的项目名称），然后选择 **Connect MCP**，即可复制 URL 以及适用于 Claude、Claude Code、Cursor 和 Codex 的步骤。

<a id="sign-in"></a>

## 登录

该服务器使用 MCP 规范定义的 OAuth 2.1 流程。客户端无需配置即可完成此流程：

1. 不带令牌的调用会返回 `401`，并附带 `WWW-Authenticate: Bearer resource_metadata="…", scope="beeuni"`。
2. 客户端会读取 `/.well-known/oauth-protected-resource/v1/mcp` 中的 RFC 9728 文档。该文档将 Beeuni 指定为授权服务器。
3. 客户端会在 `POST /v1/oauth/register` 注册自身（RFC 7591）。注册后会获得一个仅使用 PKCE 进行身份验证的公共客户端。
4. 你在 Beeuni 授权页面上批准该客户端。自行注册的客户端会标记为 **Unverified app**，并显示它将把你带回的主机。只有在你本人正在连接该客户端时才批准。
5. 客户端会将授权码换成一个 `beeuni_oat_` 访问令牌（有效期 1 小时）和一个刷新令牌（有效期 30 天，每次使用时都会轮换）。访问令牌过期后，客户端会自动刷新，无需再次询问你。

<a id="revoke-a-client"></a>

### 撤销客户端

**设置 → 个人访问密钥 → 已连接的应用**会列出你在所有账户中批准的应用，包括应用名称、登录位置和上次活跃时间。自行注册的 MCP 客户端会标记为 **Unverified app**。**撤销访问权限**会删除你的批准并撤销其令牌：该客户端的下次请求会失败，并且必须再次请求你的批准。在终端中运行：`beeuni tokens apps ls` 和 `beeuni tokens apps rm <client-id>`。这两种方式只能通过浏览器会话或个人访问令牌使用，不能使用应用自身的令牌。

<a id="what-a-connected-app-cannot-do"></a>

### 已连接的应用无法执行的操作

`beeuni` 作用域会让应用以你的身份操作：已连接的应用可以读取和更改你能读取和更改的内容。它无法创建有效期超过自身可撤销令牌的凭据。对于 `beeuni_oat_` 令牌，以下路由会返回 `403`：

- 个人访问令牌（`POST /v1/accounts/tokens`）和项目 CLI 令牌；
- 网关密钥；
- SCIM 令牌；
- OAuth 客户端及其密钥轮换；
- 服务账户；
- 已连接应用列表及其撤销操作（`/v1/oauth/grants`）。

撤销客户端后，它将无法继续访问。个人访问令牌则不同：除非你传入 `--expires`，否则它不会过期；撤销应用也不会撤销该令牌。

<a id="personal-access-token"></a>

### 个人访问令牌

不支持 OAuth 的客户端或脚本可以改为发送 `beeuni_pat_` 令牌，即 CLI 使用的令牌。使用 `beeuni tokens new <name>` 创建令牌，或在**设置 → 个人访问密钥**中创建，然后将其作为标头发送：

```json
{ "mcpServers": { "beeuni": { "url": "https://api.beeuni.ai/v1/mcp", "headers": { "Authorization": "Bearer beeuni_pat_…" } } } }
```

<a id="tools"></a>

## 工具

`tools/list` 会返回 23 个工具。标有 * 的参数为必填项。

| 工具 | 参数 | 功能 |
| --- | --- | --- |
| `list_projects` | 无 | 列出你在所有账户中可以打开的每个项目，以及其 `project_id` 和你的角色。 |
| `start_session` | `project_id`*, `prompt`*, `name`, `agent` | 在项目中使用首条提示启动会话。返回 `session_id`。 |
| `send_message` | `session_id`*, `text`* | 为会话排队一条消息；如果会话已停止，则启动会话。 |
| `read_session` | `session_id`*, `limit`, `wait_seconds` | 返回会话状态、其轮次是否处于 `idle`、`booting`、`running` 或 `queued` 状态，以及最新消息和每次工具调用的输入与输出。`limit` 默认为 10，最多为 100。`wait_seconds`（最多 45）会等待轮次结束。 |
| `list_sessions` | `project_id`*, `limit`, `cursor` | 列出你在项目中可见的会话：id、标题、状态、代理、所有者、分支和日期。`limit` 默认为 20，最多为 200。 |
| `run_command` | `session_id`*, `command`, `cwd`, `timeout_seconds`, `job_id`, `cancel` | 在会话沙盒中运行 bash 命令，并返回 stdout、stderr 和退出代码。长时间运行的命令会返回一个 `job_id`，可用于继续等待。 |
| `read_file` | `path`*, `session_id`, `project_id`, `ref`, `offset`, `limit` | 从会话沙盒读取文件，或从项目 git 仓库的 `ref` 读取文件。图片将以图片形式返回。 |
| `write_file` | `session_id`*, `path`*, `content`*, `encoding` | 在会话沙盒中写入文件，并创建其父目录。`encoding` 为 `utf8`（默认值）或 `base64`。 |
| `list_files` | `path`, `session_id`, `project_id`, `ref`, `offset` | 列出会话沙盒中的一个目录，或列出项目仓库中某个路径下的所有文件。 |
| `read_skill` | `name`, `file`, `project_id` | 列出 Beeuni 平台指南，或返回一份指南（`name`）或其中一个参考文件（`file`）。使用 `project_id` 时，会优先列出项目自身的技能；项目技能 `name` 会返回其 `SKILL.md` 和参考文件路径。 |
| `list_connectors` | `project_id`*, `connector` | 列出项目连接器：slug、提供商、是否为 `connected`（你现在可以使用）、操作数量和账户。使用 `connector` 时，会完整列出该连接器的账户。 |
| `search_connector_actions` | `project_id`*, `query`, `connector`, `limit` | 按意图查找连接器操作。返回 `tool`（`<connector>.<action>`）、`risk` 和一行描述。不会返回架构。 |
| `describe_connector_action` | `project_id`*, `tool`* | 返回某项操作的输入 JSON Schema、风险和描述。 |
| `call_connector` | `project_id`*, `tool`*, `args`, `account`, `reason` | 以你的身份运行一项操作。返回数据和执行该操作的 `account`、带有审批链接的 `pending_approval` 结果，或附有原因的拒绝信息。 |
| `upload_connector_attachment` | `project_id`*, `connector`*, `filename`*, `content_base64` 或 `session_id` + `path` | 暂存文件，并返回要放入 `args` 的 `{"$beeuni_attachment": "<id>"}` 引用。 |
| `connect_connector` | `project_id`*, `connector`*, `owner`, `label` | 返回供用户打开以连接该连接器账户的链接。 |
| `search_connector_apps` | `project_id`*, `query`*, `limit`, `cursor` | 搜索可用于添加连接器的托管应用目录。 |
| `add_connector` | `project_id`*, `app` 或 `provider` + `slug`, `name`, `url`, `transport`, `endpoint`, `spec`, `base_url` | 立即将连接器添加到项目（提交到 `beeuni.yaml` 上的 `main`，然后同步）。 |
| `remove_connector` | `project_id`*, `connector`* | 从项目中移除连接器。 |
| `beeuni` | `args`*, `project_id`, `session_id` | 以你的身份运行真实的 `beeuni` CLI，并返回 `exit_code`、`stdout`（对于 `--json` 输出则返回 `json`）和 `stderr`。参见[运行任意 CLI 命令](#run-any-cli-command)。 |
| `search_api` | `query`*, `limit` | 按关键词搜索 Beeuni API 路由。 |
| `describe_api` | `method`*, `path`* | 返回某个路由的参数、请求正文和响应架构。 |
| `call_api` | `method`*, `path`*, `project_id`, `query`, `body` | 以你的身份调用任意 `/v1/` 路由。`project_id` 会在路径中填入 `{projectId}`。 |

`search_api`、`describe_api` 和 `call_api` 涵盖 Web 应用和
[CLI](/docs/zh/cli) 的全部功能，因为它们都是同一 API 的客户端。`call_api`
会拒绝 `/v1/oauth/*` 以及任何会到达 MCP 端点的路径。请自行填写路径中的其他所有
`{placeholder}`。每次调用的授权和审计方式都与来自 Web 应用的请求相同。审计会记录每次调用及其 `credential_kind: "oauth_app"` 和已连接应用的名称，因为
API 记录的是用于身份验证的凭据，而不是客户端发送的标签。

<a id="run-any-cli-command"></a>

### 运行任意 CLI 命令

`beeuni` 工具会以你的身份运行真实的[`beeuni` CLI](/docs/zh/cli)。所有 CLI
命令都可以通过它运行，因此 MCP 服务器的访问范围与终端相同：机密、触发器、`cr`、`review`、提醒、代理、模型、网关、提供商、频道、沙盒、应用、市场、文件、访问权限、角色、权限、审计、授权、成员、群组、令牌、账单、项目、会话和 `system-skills`。一个工具可替代约 200 个子命令工具，而这些工具的数量会超过 Cursor 等客户端的工具数量上限。

`args` 是 `beeuni` 之后的 argv，每个参数对应一个数组元素。它绝不是
shell 命令行。

```json
{ "name": "beeuni", "arguments": { "args": ["--help"] } }
{ "name": "beeuni", "arguments": { "args": ["secrets", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["triggers", "ls", "--json"], "project_id": "<project_id>" } }
{ "name": "beeuni", "arguments": { "args": ["system-skills"] } }
```

- 使用 `["--help"]` 和 `["<group>", "--help"]` 进行发现。在你解析的输出中加入 `--json`。
- `project_id` 用于设置项目范围命令的项目。`session_id` 用于设置针对某个会话执行的命令的会话。
- 结果为 JSON：`exit_code`、`stdout`、`stderr`。使用 `--json` 时，命令输出会作为 JSON 值放在 `json` 中，而不是 `stdout`。超出容量的输出会被截断并标记为 `truncated`；截断后的 JSON 不是有效 JSON，因此请缩小命令范围。非零 `exit_code` 会导致 MCP 错误。每个流的上限分别为 24,000（stdout）和 8,000（stderr）个字符，结果会在 `truncated` 中说明是否达到上限。
- 运行时间超过约 45 秒的命令会被终止。结果中会包含
  `timed_out`。
- 服务器最多同时运行 4 条 CLI 命令。第五次调用会返回
  `Busy`：请重试。
- 会话、沙盒文件和连接器都有专用工具
  （`start_session`、`run_command`、`read_file`、`call_connector`）。请优先使用这些工具。

CLI 会在服务器上使用你自己的令牌，针对此 API 运行。它不会获得服务器凭据：其环境中只有你的令牌、API URL、项目和会话 ID，以及空的临时主目录和工作目录。
命令运行后，服务器会删除这两个目录。授权和审计由 API 负责：外部人员的令牌会获得与终端相同的 `403`。

这些命令会在运行前被拒绝。错误会说明原因和替代方案。

| 命令 | 原因 | 请改用 |
| --- | --- | --- |
| 任意 `--host` 或 `--host=` 标志、`hosts` | 将 CLI 指向其他服务器，并会把你的令牌发送到那里。 | 此服务器已代表你行事。 |
| `login`、`logout` | 浏览器登录和存储的令牌。 | 你已通过 MCP 连接登录。 |
| `init`、`ship`、`deploy` | 读取或写入本地目录。 | 在源文件所在的会话沙盒中使用 `run_command`。 |
| `tools` | 读取和编辑本地 `beeuni.yaml`，而服务器没有项目检出副本。 | 在会话沙盒中使用 `run_command`：在那里运行 `beeuni tools ls`。 |
| `apps deploy` | 部署本地目录，而服务器没有该目录。 | 在会话沙盒中使用 `run_command`：在那里运行 `beeuni apps deploy <path>`。 |
| `env pull`、`env push` | 写入或读取本地文件。 | `secrets ls`、`secrets set KEY=value`。 |
| `token`、`whoami --token-only` | 打印原始访问令牌。 | `whoami --json`。 |
| `update`、`uninstall` | 更改运行 CLI 的计算机。 | 无。 |
| `tui`、`t`、`connect`、`attach`、`sessions connect|shell|forward` | 需要交互式终端。 | `start_session`、`send_message`、`read_session`、`run_command`。 |
| `chat` 和 `sessions chat`，但不含 `--prompt` | 打开交互式聊天。 | `start_session`、`send_message`，或添加 `--prompt "<text>"`。 |

审计记录会将 CLI 命令记录为使用与连接上的其他调用相同的凭据
（`credential_kind: "oauth_app"`）。它无法区分 `beeuni`
工具和 `call_api`：两者都使用你的令牌访问 API。

<a id="project-skills"></a>

### 项目技能

`read_skill` 搭配 `project_id` 时，会在平台指南之前列出项目自身的技能（仓库中的
`skills/<slug>/SKILL.md` 文件，或旧版
`.beeuni/opencode/skills/`）。传入技能 `name`，即可读取其 `SKILL.md`
和参考文件路径；传入 `file`，即可读取单个参考文件。你只能看到你的角色和授权允许访问的技能。

<a id="use-your-connectors"></a>

### 使用你的连接器

连接器工具是 [`beeuni connectors`](/docs/zh/connect/connectors) CLI 的 MCP
工具。它们调用与 CLI 和 SDK 相同的 API 路由，因此连接器策略、审批和审计在所有界面上的行为都相同。

1. `list_connectors` 显示已连接的内容。带有
   `connected: false` 的连接器无法执行操作：调用 `connect_connector`，打开
   返回的链接，然后再次列出。
2. `search_connector_actions` 按意图查找操作，例如
   `send an email`。`describe_connector_action` 返回其参数。
3. `call_connector` 执行操作。结果会指出执行调用的 `account`。
   如果连接器有多个账户且未设置默认账户，则需要 `account`。
4. 对参数仅包含 ID 的写入操作（`send_draft`，
   按 ID 删除），传入 `reason`。审批者会在实际参数旁看到它。

策略可以暂缓调用以等待审批。此时，`call_connector` 会返回
带有 `approval_url` 的 `status: "pending_approval"`。用户打开链接并
批准后，在 15 分钟内使用相同的工具、参数和账户再次调用：已批准的调用就会执行一次。
`policy_block` 拒绝则为最终决定。

结果超过约 40,000 个字符时，会以带标记的预览形式返回
（`data_truncated`）。缩小参数范围后再次调用。要附加文件，请使用
`upload_connector_attachment` 暂存文件，并将返回的引用放入
`args`。提供方为 `composio` 的连接器不接受附件引用。

<a id="result-size-and-paging"></a>

### 结果大小和分页

- 工具结果会在 60,000 个字符处截断，并以
  `…[truncated at 60000 chars]` 结尾。
- `read_file` 会以分页方式返回较长的文本文件，每页最多约 50,000
  个字符。截断的结果会以可继续读取的 `offset` 结尾。`offset`
  可跳过行，`limit` 可限制返回的行数。二进制文件不会以文本形式返回：请使用 `run_command` 读取。
- `list_files` 会以相同方式截断较长的列表。传入它指定的 `offset`。
- 如果还有更多会话，`list_sessions` 会返回 `next_cursor`。将其作为 `cursor` 传回。
- `read_session` 会返回最新的 `limit` 条消息。它会截断每个工具的输入和输出；如果结果放不下，则会删除最早的消息
  （`omitted_older`）。`last_turn_error` 会指定失败的轮次。
- 一次 MCP 请求最多等待 55 秒。使用 `wait_seconds` 的 `read_session`，以及仍在启动的沙盒，都会在此之前停止：请再次调用。

<a id="sandboxes"></a>

### 沙盒

配合 `session_id` 使用 `run_command`、`read_file`、`write_file` 和 `list_files`，
即可访问会话正在运行的沙盒，其方式与 Web 终端和文件面板相同。相对路径会以 `/workspace`（会话的 Git 检出目录）为基准解析。停止的沙盒会在首次调用时启动。沙盒中的 `beeuni` CLI
已使用当前会话的身份登录。如果存在 `project_id` 且没有 `session_id`，则 `read_file`
和 `list_files` 会读取项目的 Git 仓库，且不会启动沙盒。

命令可能运行数分钟。一次工具调用会等待约 50 秒。如果届时命令仍在运行，`run_command` 会返回 `status: running`、一个
`job_id` 和截至目前的输出。使用该 `job_id` 调用 `run_command` 继续等待，或使用 `cancel: true` 停止命令。`timeout_seconds`（默认值 600，
最大值 86400）会在命令运行过久时将其停止，并返回退出代码 `124`。输出会保存在沙盒中的 `~/.cache/beeuni-mcp/jobs/<job_id>/`；工具结果会显示每个输出流的最后 24,000 字节。沙盒停止时，其中运行的命令也会随之停止。

服务器是无状态的：它以 JSON 响应 `POST`，并以 `405` 响应 `GET` 和 `DELETE`。