Executor 怎么用:一个 MCP 端点接所有 Agent 工具

Claude Code、Cursor、Codex 各装一遍同样的 MCP 服务器,同一个 API 密钥粘三处,换台电脑再来一遍,这是很多人用多个 Agent 的日常。开源项目 Executor(MIT 许可,GitHub 约 4,420 星,2026-11-12 统计)的做法是把账号和工具集中放在一处,所有 Agent 只连它的一个 MCP 端点,密钥不进 Agent。这篇按官方文档讲清它的模型、怎么装、怎么接各家客户端,以及审批该放在哪。
它解决的是「每个 Agent 一套集成」
官方仓库 README 列的痛点是:每个 Agent 都要自己一份集成,同样的 API 密钥贴好几处,同样的 MCP 服务器接好几遍,各家对「这个工具允许做什么」也没有统一的规则。Executor 夹在中间:工具加一次、凭据给一次、规则定一次,所有支持 MCP 的 Agent 共用。
当前文档对应的是 2.0 测试版(文档要求 executor --version 显示 2.0.0-beta.42),概念按 2.0 的说法:
- 账号(account):你在某个服务上的一份凭据,比如一个 API 密钥或一次 OAuth 登录。存一次,多个应用可以共用,不复制凭据。同一服务可以存多个,比如「工作 Vercel」「个人 Vercel」,还能给账号写一段给 Agent 看的说明,例如「只读;写操作用沙盒账号」。
- 应用(app):把账号变成工具的小程序。可以从目录里加,也可以导入现成的 MCP 服务器、OpenAPI 或 GraphQL 文档,或者自己写。
- 工具(tool):应用暴露的一个操作,分只读的 query 和写入的 mutation。
Agent 调工具时,凭据由 Executor 在应用内部附上,Agent 自己看不到。
端点只有一个,工具列表也不会膨胀
MCP 服务器接多了,Agent 的工具列表会越来越长,上下文也跟着涨。Executor 的 /mcp 端点不按应用逐个暴露工具,不管你加了多少应用,默认模式下对外就这 6 个(native 模式下没有 resume):
| MCP 工具 | 作用 |
|---|---|
| skills | 读取应用附带的说明(Skill),不连账号、不执行代码 |
| search | 按路径、描述、标签里的词找工具,返回准确路径和输入类型 |
| describe | 返回指定工具的完整描述和签名(含输出类型) |
| call | 按路径直接调一个或多个工具,多个调用并发执行,一个失败不影响其他 |
| execute | 跑一段 JavaScript,把多个工具串起来,只返回需要的字段 |
| resume | 继续因审批或等待输入而暂停的调用 |
execute 就是常说的 Code Mode(思路见 Agent Code Mode 教程):上一个结果要喂给下一个调用,或者结果很大要先筛一遍,就让 Agent 写一小段程序。这段程序跑在沙盒解释器里,没有 fetch、没有 process、没有文件系统、没有定时器、不能 import,唯一的出口是工具调用。服务端写死的上限是:程序源码 65,536 个字符、100 次工具调用、5 分钟。官方也写明,这些限制靠协作约束,没有做进程级隔离。
应用加得再多,Agent 看到的始终是 search、call、execute 这几个工具,要用什么先搜出来再调。
第一步:选一种跑法
- 托管:登录 app.executor.sh,什么都不用装。端点是
https://mcp.executor.sh/mcp。 - 本机:账号留在你自己的电脑上。本地端点默认
http://127.0.0.1:4312/mcp。 - 自托管:用 Docker 跑在自己的服务器上,配自己的数据库,端点是你的域名加
/mcp。
三种跑法运行同样的应用、暴露同样的端点,托管版和自托管版多了组织管理和浏览器登录。本机安装的几种方式(官方文档原样):
# npm(Node 14.18.0 及以上,包本身只是启动器,首次运行会下载对应平台的运行时)
npm i -g executor@beta
executor --version
executor
# 不装 Node(macOS / Linux),脚本会校验 SHA256SUMS
curl -fsSL https://executor.sh/docs/install.sh | sh
# Homebrew
brew install usefulsoftwareco/tap/executor-beta
运行 executor 会在后台启动服务、打开浏览器里的控制台,然后退出。首次启动时,它把 API 密钥和加密密钥存进 macOS 钥匙串、Windows 凭据管理器或 Linux Secret Service;没有凭据存储的 Linux 服务器上,会退回到数据目录下只有当前用户可读的 keys.json,这个目录要自己保管好。
第二步:加应用、连账号
在控制台里添加应用:从目录里选,或者贴一个 MCP 服务器 / OpenAPI / GraphQL 地址导入。然后到应用的 Accounts 页,为每个需要的服务连一个账号(粘 API 密钥或走 OAuth),也可以直接关联之前给别的应用存过的账号。
团队使用时要先想好一件事:应用对账号的需求分两种。user 需求由每个调用者用自己的账号填,各人调用走各人的凭据;app 需求由有权限的人关联一个共用账号,所有人都走它。像个人邮箱这种显然该用前者。
第三步:把各家 Agent 接上来
官方给的命令(托管端点;本机或自托管把地址换成自己的):
# Claude Code:--scope user 表示所有项目都能用
claude mcp add --transport http --scope user executor 'https://mcp.executor.sh/mcp'
# 然后在 Claude Code 里运行 /mcp,浏览器里登录并批准
# Codex(CLI 或 IDE 扩展,直接加 MCP 服务器)
codex mcp add executor --url 'https://mcp.executor.sh/mcp'
codex mcp login executor
# Cursor 及其他客户端:安装器会识别客户端并写好配置
npx add-mcp 'https://mcp.executor.sh/mcp' --transport http --name executor
连本机服务时,客户端同样走浏览器登录;不支持登录的客户端可以把本地 API 密钥作为 Bearer 头发过去:
npx add-mcp 'http://127.0.0.1:4312/mcp' --transport http --name executor \
--header 'Authorization: Bearer <key>'
大多数客户端只在启动时加载 MCP 服务器,加完要重启客户端或开新会话,工具才会出现。
第四步:给写操作加审批
Executor 的审批定义在每个 query / mutation 上,没有应用级的总开关,也不会因为某个操作「看起来是只读」就自动放行。最简单的两种是 always()(每次问人)和 never()(直接执行);要按输入做判断就写一个函数,返回 approved、denied 或 user-approval 三者之一,比如小额退款直接过、大额要人批。
导入的 MCP、OpenAPI、GraphQL 可以用 withApprovals 批量定规则,官方示例:
// 对 OpenAPI / GraphQL:所有写操作都先问人
withApprovals(api, (tool) => (tool.kind === "mutation" ? always() : undefined));
// 对 MCP:服务器标记为破坏性的工具先问人
withApprovals(server, (tool) =>
toolAnnotations(tool)?.destructiveHint === true ? always() : undefined,
);
从控制台添加的 MCP 服务器默认就带第二条规则。
审批在哪里弹出,由端点地址决定,而且在发放连接时就固定下来:
- model(默认,
/mcp):Agent 把请求转述给你,再带着你的回答调resume。 - native(
/mcp?elicitation_mode=native):用 MCP 客户端自己的确认框,需要客户端支持表单征询(form elicitation)。 - browser(
/mcp?elicitation_mode=browser):在浏览器里一个已登录的页面上确认。官方的建议是,不想让 Agent 来「转达」审批问题时就用这个。
常见坑
- 加完工具不出现:客户端没重启。另外在
execute里,工具发现结果不跨变更缓存,加了或改了应用后要在新的execute里重新tools.search。 - 重启电脑后连不上:本机的后台服务不会开机自启,重启后要运行
executor或executor service start。 - 版本对不上:
executor --version还显示 v1,说明 PATH 里有旧安装,用type -a executor(Windows 用where.exe executor)查是哪个,再用当初的包管理器卸掉。GitHub 首页 README 里的部分命令和概念还是 1.x 的说法,以 executor.sh/docs 为准。 - 以为改 URL 就能换审批方式:审批模式写在授权里,已发放的连接改查询参数不会生效,要重新连。
- 把沙盒当成强隔离:Code Mode 的限制是协作式的,敏感写操作还是要靠审批规则兜底。
完成标准
- 至少两个 Agent(比如 Claude Code 和 Cursor)连的是同一个 Executor 端点,各自的配置里没有任何服务的 API 密钥。
- 在 Agent 里让它「列出 Executor 里可用的应用和工具」,能返回你加的应用。
- 每个导入的服务都定了审批规则:写操作或破坏性操作需要确认。
- 团队用的话,审批模式选了 browser 或 native,而不是让 Agent 转述。
最后
先挑一个你在两个以上 Agent 里重复配置过的服务,把它搬进 Executor,删掉各客户端里那份密钥,跑一周看看顺不顺手,再决定要不要把其他 MCP 服务器也搬进来。