MCP 服务器

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

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

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

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

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

添加到客户端

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

Claude Code

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

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

ChatGPT

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

Cursor

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

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

VS Code

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

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

Codex

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

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

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

其他客户端

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

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

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

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

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

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

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

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

个人访问令牌

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

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

工具

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

运行任意 CLI 命令

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

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

{ "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`
`chat` 和 `sessions chat`，但不含 `--prompt`	打开交互式聊天。	`start_session`、`send_message`，或添加 `--prompt "<text>"`。

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

项目技能

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

使用你的连接器

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

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

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

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

结果大小和分页

工具结果会在 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，以及仍在启动的沙盒，都会在此之前停止：请再次调用。

沙盒

配合 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。