Подключение MCP-сервера
MCP-сервер Aggrega — это команда aggrega mcp, и единственное предварительное требование для него — исполняемый файл aggrega: раздел Установка исполняемого файла устанавливает его одной командой. Сервер запускается как подпроцесс вашего клиента через stdio, читает схемы из исполняемого файла, а страницы документации — из копии, которую однократно загружает в кеш вашей машины, и не требует отдельной службы, порта или учётной записи. Если сервер для вас уже запускает кто-то другой, вам не нужны ни исполняемый файл, ни всё описанное здесь: см. Сервер, доступный по HTTPS.
Клиенты, которые добавляют его одной командой
Ассистент с установленным плагином Aggrega уже подключён. Установка плагина добавляет навык Aggrega и сервер за один шаг — в Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro и OpenClaw, как описано в разделе Установка плагина, — поэтому для подключения этого ассистента ничего другого с этой страницы не нужно. Плагин запускает aggrega mcp с помощью aggrega, найденного в PATH, с которым был запущен ассистент, поэтому двоичный файл должен быть установлен именно там. Некоторые ассистенты запускают сервер плагина в собственной папке плагина, а не в вашем проекте, — так делает 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 и подключиться к серверу — по одному промпту, который вы ему вставите: см. Настройка 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" — место установки в Linux для пользователя с именем you). Всё остальное остаётся без изменений.
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/config.toml для одного проекта, которому Codex доверяет, — каждый в виде таблицы, названной по имени сервера:
[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 не содержит собственной программы. Он запускает исполняемый файл aggrega, уже установленный на вашем компьютере, с единственным аргументом mcp и обменивается данными по протоколу через стандартные ввод и вывод этого процесса — это тот же сервер, который запускает каждая из приведённых выше записей. Если вы не выберете другой исполняемый файл, он передаёт Claude Desktop имя команды aggrega, как и каждая из приведённых выше записей, поэтому приложение ищет aggrega в PATH, с которым оно было запущено; и он передаёт этому серверу выбранное вами рабочее пространство. Чтобы добавить его:
- Установите исполняемый файл
aggrega, как описано в разделе Установка исполняемого файла. И команда установки, и описанные там ручные шаги помещают его в вашу собственную папку — в Windows это%LOCALAPPDATA%\Programs\aggrega, а не системная папка, такая какC:\Windows\System32, — чтобы его можно было заменить без прав администратора. - Установите
aggrega-<version>.mcpbиз настроек расширений Claude Desktop. - Задайте настройки пакета; ни одна из них не обязательна. Path to the aggrega executable — программа, которую запускает пакет; по умолчанию это имя команды
aggrega, которое приложение ищет вPATH, с которым оно было запущено. Папка, добавленная в вашPATHво время работы приложения, — как добавляют свои папки установщик Windows и команда установки в Windows, — становится доступна приложению только после того, как оно будет закрыто и запущено снова, как в шаге 4, а приложение, запущенное из графической среды, может не видеть тот жеPATH, что и ваш терминал (см. Примечание оPATH). Оставьте значение по умолчанию, еслиaggregaв этомPATH— нужный вам исполняемый файл. Вместо этого укажите в поле полный путь к исполняемому файлу, если нужного вам файла нет в этомPATHили это другойaggrega, чем первый найденный там: в macOS и Linux для места установки —aggregaв.local/binв вашей домашней папке, например/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 они могут находиться в папке пакета в локальном каталоге данных приложений, а не в %APPDATA%\Claude\logs, даже если Claude Desktop был установлен из собственного дистрибутива: в %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-транспорте, который и использует этот сервер.
Токен получает ваш клиент, а не вы. Ничего, связанного со входом, в записи не настраивается: на запрос без аутентификации сервер отвечает, указывая документ, в котором сказано, какой сервер авторизации выдаёт его токены, а клиент, поддерживающий поток авторизации протокола, читает этот документ, направляет вас на вход и прикрепляет полученный токен к каждому последующему запросу. Имена областей доступа, которые он может запросить, опубликованы в том же документе. Клиент, не реализующий этот поток, не может обратиться к такому серверу, и ничто, добавленное вами в запись, его не заменит.
Инструмент, на который не распространяются области доступа вашего входа, всё равно есть в списке инструментов. Его вызов отклоняется с указанием области, которая его разрешила бы, а клиент, реализующий повышение прав (step-up) протокола, отвечает на такой отказ, предлагая вам войти снова с этой областью. Клиенту, не поддерживающему повышение прав, всё же можно выдать области записи: тот, кто управляет сервером авторизации, делает их областями по умолчанию для этого клиента, и уже его первый вход их содержит — ценой того, что каждый вход через этот клиент затем получает право записи. В разделе Что может быть доступно вызывающей стороне описано, что разрешает каждая область и как эта настройка ведёт себя для клиента, который регистрируется заново при каждом подключении.
Что требуется такому серверу и что настраивает его оператор, описано в разделе aggrega mcp справочника.
Проверка подключения
После повторного подключения клиента убедитесь, что интеграция работает: клиент должен показать промпты Aggrega для авторинга (по одному для ролей разработчика, архитектора и эксплуатации, а также шаблон для каждой сущности) и инструменты авторинга — среди них scaffold, validate, describe и get-schema. Попросите ассистента создать заготовку компонента, и он должен вернуть каркас с полями, которые требует сущность Component. Если ничего не появляется, проверьте, что aggrega version запускается из терминала и что command клиента указывает на исполняемый файл, — примечание о PATH выше описывает частую причину.