连接 MCP 服务器
Aggrega 的 MCP 服务器就是 aggrega mcp 命令,而 aggrega 二进制文件是它唯一的前提条件:安装二进制文件用一条命令即可安装它。该服务器作为客户端的子进程通过 stdio 运行,从二进制文件读取其 schema,从一次性获取到本机缓存中的副本读取其文档页面,不需要单独的服务、端口或账户。如果已有其他人为你运行服务器,你既不需要该二进制文件,也不需要以上任何内容:参见通过 HTTPS 访问的服务器。
用一条命令即可添加的客户端
已安装 Aggrega 插件的助手已经完成连接。安装插件会一步添加 Aggrega 技能和服务器——在 Claude Code、Codex、GitHub Copilot、Gemini CLI、Antigravity、Cursor、Kiro 和 OpenClaw 中均是如此,如安装插件所述——因此连接该助手不再需要本页的其他任何内容。插件使用助手启动时所用 PATH 上找到的 aggrega 来启动 aggrega mcp,因此二进制文件必须安装在那里。有些助手会在插件自己的文件夹中启动插件的服务器,而不是在你的项目中——Codex 就是如此——此时助手会在接受该参数的调用中将你项目的文件夹指定为 workspace_root;技能会要求助手检查服务器在哪个工作区中响应。
不使用插件时,请使用客户端自己的命令添加服务器。在 Claude Code 中:
claude mcp add --transport stdio aggrega -- aggrega mcp在 Codex 中:
codex mcp add aggrega -- aggrega mcp在 Gemini CLI 中:
gemini mcp add aggrega aggrega mcp其他所有客户端
大多数支持 MCP 的客户端以相同的方式启动服务器——它们运行 aggrega 命令并带上单个 mcp 参数,通过该进程的标准输入和输出使用该协议通信。它们之间的差别在于各自把服务器列表保存在哪里,以及如何称呼其中的条目。通用的形式如下:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}客户端重启并连接后,Aggrega 的编写提示、资源和工具即可使用。你的助手可以用 Aggrega 做什么介绍了它们,编写 Aggrega 文件说明了如何使用它们,aggrega mcp 参考则介绍该命令本身。
条目中没有任何内容用于选择协议修订版本。 Aggrega 同时支持 2026-07-28 和 2025-06-18,无论是通过标准输入和输出还是通过 HTTPS,因此使用其中任一版本的客户端都能连接,并获得相同的提示、资源和工具。客户端请求哪个版本是在通信过程中协商确定的,而不是在你的配置中设定。
能够运行命令的助手可以自行完成所有这些操作——安装二进制文件、添加 Aggrega skill 并连接到服务器——只需你粘贴给它的一条提示:参见借助 AI 助手设置 Aggrega。
各客户端保存服务器列表的位置
| 客户端 | 列表所在位置 | 条目的名称 |
|---|---|---|
| Claude Code | claude mcp add,或项目中的 .mcp.json 文件 | mcpServers |
| Claude Desktop | 本地服务器使用其扩展设置;通过 HTTPS 访问的服务器使用其连接器设置 | 参见 Claude Desktop |
| Cursor | .cursor/mcp.json 用于单个工作区,或用户级的 mcp.json 用于所有工作区 | mcpServers |
| Gemini CLI | gemini mcp add,或对所有项目使用 ~/.gemini/settings.json,对单个项目使用 .gemini/settings.json | mcpServers |
| Codex CLI | codex mcp add,或对所有项目使用 ~/.codex/config.toml,对单个受信任的项目使用 .codex/config.toml | 一个 [mcp_servers.aggrega] 表——参见 Codex CLI |
| Zed | Settings → AI → MCP Servers,它会将条目写入 Zed 的设置文件 | context_servers——参见 Zed |
| Visual Studio Code | 用户配置文件中的 mcp.json,或用于单个工作区的 .vscode/mcp.json | servers——参见 Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add,或它保存在你主目录中的 mcp-config.json 文件 | mcpServers |
| Antigravity | 可从其设置中打开的 mcp_config.json 文件 | mcpServers |
| Windsurf | 可从其设置中打开的 mcp_config.json 文件 | mcpServers |
| Cline | 其 MCP 设置,底层为 cline_mcp_settings.json 文件 | mcpServers |
除下文单独成节的四个客户端外,表中的每个客户端都完全按照上面的写法接受该条目,放在其所在行列出的路径中。未列出的客户端只要读取上述某种形式的服务器列表,也能以相同方式连接。
关于 PATH 的说明
从图形环境启动的客户端并不总是继承与你的终端相同的 PATH。如果客户端报告找不到 aggrega 命令,请将 "command": "aggrega" 替换为该二进制文件的绝对路径(例如 "command": "/home/you/.local/bin/aggrega",即名为 you 的用户在 Linux 上的安装位置)。其余内容保持不变。
Visual Studio Code
Visual Studio Code 将其服务器保存在 servers 而不是 mcpServers 下,并且每个条目都指明其使用的传输方式:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex 将其服务器保存在 TOML 而不是 JSON 中——对所有项目保存在 ~/.codex/config.toml 中,对 Codex 信任的单个项目保存在 .codex/config.toml 中——每个服务器都是一个以服务器命名的表:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp,即上文中的命令,会为你写入同一个表。Codex IDE 扩展和 ChatGPT 桌面应用读取同一个文件,因此这一个条目可同时用于这三者。
Zed
Zed 将其服务器保存在设置文件的 context_servers 下。可以从 Settings → AI → MCP Servers 添加服务器(先点 Add Server,再点 Add Local Server),这会将条目写入该文件;也可以从命令面板运行 zed: open settings file,然后自己添加条目:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed 支持该协议的工具和提示,因此它的智能体可以使用 Aggrega 的工具和编写提示,但无法使用服务器同样提供的资源。
Claude Desktop
Claude Desktop 通过扩展包安装本地服务器——扩展包把服务器连同描述它的清单打包成一个可安装文件,并从其扩展设置中添加——而不是通过配置文件中的条目安装。每个 Aggrega 版本都会在其预构建二进制文件旁附带这样一个扩展包 aggrega-<version>.mcpb。
Aggrega 的扩展包本身不含任何程序。它以单个 mcp 参数启动你机器上已安装的 aggrega 可执行文件,并通过该进程的标准输入和输出使用协议通信——与上文每个条目启动的是同一个服务器。除非你选择其他可执行文件,否则它会像上文每个条目一样,把命令名 aggrega 交给 Claude Desktop,因此应用会在其启动时所用的 PATH 中查找 aggrega;它还会把你选择的工作区交给该服务器。添加步骤如下:
- 按照安装二进制文件中的说明安装
aggrega二进制文件。那里的安装命令和手动步骤都会把它放在你自己的文件夹中(在 Windows 上是%LOCALAPPDATA%\Programs\aggrega,而不是C:\Windows\System32这类系统文件夹),这样无需管理员权限即可替换它。 - 从 Claude Desktop 的扩展设置中安装
aggrega-<version>.mcpb。 - 配置扩展包的设置;两项均非必填。Path to the aggrega executable 是扩展包启动的程序,其默认值为命令名
aggrega,应用会在其启动时所用的PATH中查找它。在应用运行期间添加到你的PATH中的文件夹——Windows 安装程序和 Windows 上的安装命令都会添加各自的文件夹——只有在应用退出并重新启动后才会对其生效,如第 4 步所述;而且从图形环境启动的应用可能看不到与你的终端相同的PATH(参见关于PATH的说明)。当该PATH上的aggrega就是你想要的可执行文件时,保留默认值即可。当你想要的可执行文件不在该PATH上,或者与在那里找到的第一个aggrega不是同一个时,请改为将该字段设为某个可执行文件的完整路径——在 macOS 和 Linux 上,对于安装位置,是你主文件夹中.local/bin里的aggrega,例如/Users/you/.local/bin/aggrega;在 Windows 上是以aggrega.exe结尾的完整路径,例如C:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe。要恢复默认值,请将该字段设为aggrega,而不是将其清空。如果根本没有安装aggrega,请按第 1 步所述进行安装。Workspace folder 是助手所工作的 Aggrega 工作区的文件夹:即存放你项目的.aggrega-config.yaml的文件夹。请设置这一项:在你选择文件夹之前它为空,而在它为空期间,扩展包会把空的AGGREGA_WORKSPACE_ROOT交给服务器,因此服务器会对助手在该工作区中发出的每个请求返回拒绝,说明 Workspace folder 设置为空,并提示你将其设为存放工作区.aggrega-config.yaml的文件夹,而不会在 Claude Desktop 启动它时所在的文件夹中工作。扩展包仅在应用启动服务器时才把该文件夹交给服务器,因此在服务器运行期间设置的文件夹,要等你在扩展设置中关闭并重新开启该扩展,或按第 4 步重启应用后才会生效。 - 完全退出 Claude Desktop,然后重新启动。应用已启动的服务器会继续运行,重命名可执行文件也不会使其停止,因此更改的设置只有在应用再次启动服务器后才会生效:即应用退出并重新启动之后,或者对于 Workspace folder,在扩展关闭并重新开启之后。在 Windows 上,可通过任务管理器查看
aggrega进程是否仍在运行。
未指定自身工作区的每个请求,都在该工作区文件夹中得到应答。 Claude Desktop 会在它自己选择的文件夹中启动服务器,而不是在你的项目中,因此扩展包通过环境中的 AGGREGA_WORKSPACE_ROOT 变量把你选择的文件夹传给服务器,而不是作为应用所组装命令行上的参数。服务器把该文件夹直接作为工作区根目录,正如每个命令接受 --workspace-root 的方式一样:它不会向上查找外层工作区,因此请选择存放 .aggrega-config.yaml 的文件夹,而不是其中的子文件夹。要在另一个工作区中工作,请更改该设置,并按第 4 步重启应用。以相对 workspace_root 指定自身工作区的请求,同样会以该工作区文件夹为基准解析该路径,因此提示词可以指定其中的某个文件夹——例如 quickstart-ai/1——而无需知道该文件夹在你机器上的位置;绝对 workspace_root 则按原样使用。在该设置为空期间,相对路径会得到与未指定工作区的请求相同的拒绝。
由于扩展包不指定任何平台的可执行文件,同一个文件适用于它声明的所有平台:macOS、Windows 和 Linux。
服务器会报告扩展包启动的是哪个 aggrega。 Claude Desktop 的扩展设置列出的是扩展包自身的版本——即它所属的版本发布——而不是它所启动的可执行文件的版本。两者分别安装,因此可能来自不同的版本发布。扩展包通过环境中的 AGGREGA_BUNDLE_VERSION 变量把自身版本交给服务器,服务器会同时报告两者:不带参数调用 describe-capabilities(助手用来了解服务器提供哪些功能的工具)所得的应答,以一行注明可执行文件版本和扩展包版本的文字开头,并在其结构化部分中以 version_summary 携带同一行,因此当助手被问到正在运行的是哪个版本的 Aggrega 时,无论应用交给它应答的哪一部分,都能从中读到两者。若两者来自不同的版本发布,这一行会说明这一点并列出两者,服务器在连接时交给助手的指引也以同一句话开头。版本不同不会导致任何拒绝,服务器照常应答每个请求;报告它是为了让你知道扩展包正在运行哪个可执行文件。要使两者一致,请安装与你的可执行文件同一版本发布的 aggrega-<version>.mcpb(在终端运行 aggrega version 可打印该版本),或将 Path to the aggrega executable 设为扩展包所属版本发布中某个 aggrega 的完整路径,然后按第 4 步重启应用。
Claude Desktop 自身的日志会显示它启动了什么。 在 Windows 上,即使 Claude Desktop 是通过其官方下载安装的,日志也可能位于本地应用数据目录下的某个包文件夹中,而不是 %APPDATA%\Claude\logs 下:即 %LOCALAPPDATA%\Packages\ 下名称以 Claude_ 开头的文件夹中的 LocalCache\Local\Claude\logs。其中的文件包括 mcp.log 和 mcp-server-Aggrega.log,后者记录 Aggrega 服务器写入其标准错误的内容。包含 Using MCP server command: 的一行列出了应用启动的命令,该命令取自扩展包的 Path to the aggrega executable 设置。若该设置指定的路径上什么都没有,日志会记录 Windows 命令解释器的消息,指出该路径无法识别为命令,随后报告服务器无法启动。若工作区文件夹不存在——被重命名、移动或从未创建——服务器仍会照常启动,并以拒绝应答助手在该工作区中发出的每个请求,因此助手收到的是作为其请求应答的拒绝,而不是应用报告连接失败。该拒绝会指出 AGGREGA_WORKSPACE_ROOT 是扩展包 Workspace folder 设置所设定的变量,并按应用传入的原样引用该文件夹;mcp-server-Aggrega.log 也记录同样的拒绝。Workspace folder 留空时也以同样方式应答,返回第 3 步所述指出该设置为空的拒绝,日志同样会记录。请更正该设置,并按第 4 步重启应用。
Claude Desktop 的连接器设置是另一种途径,用于通过 HTTPS 访问的服务器:参见通过 HTTPS 访问的服务器。
当客户端无法接受全部工具时
Aggrega 会公布其全部工具,并由客户端决定向模型呈现其中多少。有些客户端限制一次可注册的工具数量,并丢弃其余工具。遇到这种情况时,mcp.announce_tools 可将服务器公布的工具缩减为你指定的工具——参见缩小服务器公布的范围。
通过 HTTPS 访问的服务器
上面的每个条目都由客户端自行启动服务器。由他人运行的服务器(在某台主机上长期运行的单个进程,服务于一个工作区)则改为通过网络访问,其条目指定的是一个地址而不是命令:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}路径始终是 /mcp;主机则是运维人员为该服务器发布的地址。请向他们索取。Gemini CLI 在 httpUrl 而不是 url 下接收该地址:它将 url 视为使用较旧的事件流传输的服务器,而将 httpUrl 视为使用可流式 HTTP 传输的服务器,后者正是此服务器所使用的传输。
令牌由你的客户端获取,而不是由你获取。 条目中无需配置任何登录相关的内容:服务器在收到未经身份验证的请求时,会给出一份文档,说明由哪个授权服务器签发其令牌;支持该协议授权流程的客户端会读取该文档,引导你登录,并将收到的令牌附加到之后的每个请求上。客户端可以请求的权限范围(scope)名称也发布在同一份文档中。未实现该流程的客户端无法访问这类服务器,你在条目中添加的任何内容都无法替代它。
登录所获权限范围覆盖不到的工具仍会出现在工具列表中。 调用它会被拒绝,拒绝信息会指出可以允许该调用的权限范围;实现了该协议权限提升(step-up)的客户端会通过请你针对该权限范围重新登录来响应这一拒绝。对于不支持权限提升的客户端,仍可以为其授予写入权限范围:由运行授权服务器的人将这些权限范围设为该客户端的默认权限范围,这样它首次登录时就已带有这些权限范围,代价是此后通过该客户端的每次登录都带有写入权限。调用方可以访问什么说明了每个权限范围允许的内容,以及该设置对于每次连接时都重新注册自身的客户端如何生效。
这类服务器有哪些要求、其运维人员需要配置什么,请参阅 aggrega mcp 参考。
验证连接
客户端重新连接后,确认集成已生效:客户端应列出 Aggrega 的编写提示(开发者、架构师和运维角色各一个,另加一个按实体的模板)以及编写工具,其中包括 scaffold、validate、describe 和 get-schema。让助手搭建一个组件,它应返回一个骨架,其中包含 Component 所需的字段。如果没有任何内容出现,请检查 aggrega version 能否在终端中运行,以及客户端的 command 是否解析到该二进制文件——上文的 PATH 说明涵盖了常见原因。