Підключення сервера 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-транспорті, яким і користується цей сервер.
Токен отримує ваш клієнт, а не ви. У записі нічого не налаштовується щодо входу: на неавтентифікований запит сервер відповідає, називаючи документ, у якому вказано, який сервер авторизації видає його токени, а клієнт, що підтримує потік авторизації протоколу, читає цей документ, пропонує вам увійти й додає отриманий токен до кожного наступного запиту. Назви областей доступу (scopes), які він може запитувати, опубліковано в тому самому документі. Клієнт, який не реалізує цей потік, не може звернутися до сервера такого типу, і ніщо, що ви додасте до запису, його не замінить.
Інструмент, до якого не сягають області доступу вашого входу, усе одно є в списку інструментів. Виклик його відхиляється з назвою області доступу, яка б його дозволила, а клієнт, що реалізує step-up протоколу, відповідає на таку відмову пропозицією увійти знову для цієї області. Клієнтові, який не підтримує step-up, усе одно можна надати області доступу на запис: той, хто керує сервером авторизації, робить їх областями за замовчуванням для цього клієнта, тож уже перший вхід їх містить — ціною того, що кожен вхід через цей клієнт тоді матиме доступ на запис. У розділі Що може бути доступно викликачеві описано, що дозволяє кожна область доступу і як поводиться це налаштування для клієнта, який реєструється заново під час кожного підключення.
Що потрібно такому серверу і що налаштовує його оператор, описано в розділі aggrega mcp довідника.
Перевірка з’єднання
Після повторного підключення клієнта переконайтеся, що інтеграція працює: клієнт має показати промпти для авторингу Aggrega (по одному для ролей розробника, архітектора та експлуатації, а також шаблон для кожного типу сутності) та інструменти авторингу — серед них scaffold, validate, describe і get-schema. Попросіть асистента створити заготовку компонента, і він має повернути каркас із полями, яких вимагає сутність Component. Якщо нічого не з’являється, перевірте, що aggrega version запускається з термінала і що command клієнта вказує на бінарний файл, — примітка про PATH вище описує найпоширенішу причину.