Menghubungkan server MCP
Server MCP Aggrega adalah perintah aggrega mcp, dan binary aggrega adalah satu-satunya prasyaratnya: Menginstal binary menginstalnya dengan satu perintah. Server berjalan sebagai subproses klien Anda melalui stdio, membaca skemanya dari binary dan halaman dokumentasinya dari salinan yang diambilnya sekali ke cache mesin Anda, dan tidak memerlukan layanan, port, atau akun terpisah. Jika orang lain sudah menjalankan server untuk Anda, Anda tidak memerlukan binary maupun hal-hal ini: lihat Server yang dijangkau melalui HTTPS.
Klien yang menambahkannya dengan satu perintah
Asisten yang sudah memasang plugin Aggrega sudah terhubung. Memasang plugin menambahkan skill Aggrega dan server dalam satu langkah — di Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro, dan OpenClaw, seperti yang dijelaskan di Memasang plugin — sehingga tidak ada hal lain di halaman ini yang diperlukan untuk menghubungkan asisten tersebut. Plugin menjalankan aggrega mcp dengan aggrega yang ditemukan di PATH yang digunakan saat asisten dijalankan, sehingga biner harus dipasang di sana. Beberapa asisten menjalankan server plugin di folder milik plugin itu sendiri, bukan di proyek Anda — Codex melakukannya — dan asisten kemudian menyebutkan folder proyek Anda sebagai workspace_root pada panggilan yang menerimanya; skill memintanya untuk memeriksa di workspace mana server menjawab.
Tanpa plugin, tambahkan server dengan perintah milik klien itu sendiri. Di Claude Code:
claude mcp add --transport stdio aggrega -- aggrega mcpDi Codex:
codex mcp add aggrega -- aggrega mcpDi Gemini CLI:
gemini mcp add aggrega aggrega mcpSemua klien lainnya
Sebagian besar klien yang mendukung MCP menjalankan server dengan cara yang sama — mereka menjalankan perintah aggrega dengan satu argumen mcp dan berkomunikasi dengan protokol melalui input dan output standar proses. Yang berbeda di antara mereka adalah di mana masing-masing menyimpan daftar servernya dan apa sebutan untuk entri di dalamnya. Bentuk umumnya:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Setelah klien dimulai ulang dan terhubung, prompt, resource, dan tool penulisan Aggrega menjadi tersedia. Apa yang dapat dilakukan asisten Anda dengan Aggrega menjelaskannya, Menulis file Aggrega menunjukkan apa yang dapat dilakukan dengannya, dan referensi aggrega mcp membahas perintah itu sendiri.
Tidak ada apa pun dalam entri yang memilih revisi protokol. Aggrega mendukung 2026-07-28 dan 2025-06-18, baik melalui input dan output standar maupun melalui HTTPS, sehingga klien dari salah satunya dapat terhubung dan menjangkau prompt, resource, dan tool yang sama. Revisi mana yang diminta klien ditentukan saat komunikasi berlangsung, bukan di konfigurasi Anda.
Asisten yang dapat menjalankan perintah dapat melakukan semua ini sendiri — menginstal binary, menambahkan skill Aggrega, dan terhubung ke server — dari satu prompt yang Anda tempelkan: lihat Menyiapkan Aggrega dengan asisten AI Anda.
Tempat setiap klien menyimpan daftar servernya
| Klien | Lokasi daftar | Sebutan entri |
|---|---|---|
| Claude Code | claude mcp add, atau file .mcp.json di dalam proyek | mcpServers |
| Claude Desktop | pengaturan ekstensinya untuk server lokal; pengaturan konektornya untuk server yang dijangkau melalui HTTPS | lihat Claude Desktop |
| Cursor | .cursor/mcp.json untuk satu workspace, atau mcp.json tingkat pengguna untuk setiap workspace | mcpServers |
| Gemini CLI | gemini mcp add, atau ~/.gemini/settings.json untuk setiap proyek dan .gemini/settings.json untuk satu proyek | mcpServers |
| Codex CLI | codex mcp add, atau ~/.codex/config.toml untuk setiap proyek dan .codex/config.toml untuk satu proyek tepercaya | tabel [mcp_servers.aggrega] — lihat Codex CLI |
| Zed | Settings → AI → MCP Servers, yang menulis entri ke file pengaturan Zed | context_servers — lihat Zed |
| Visual Studio Code | mcp.json di profil pengguna Anda, atau .vscode/mcp.json untuk satu workspace | servers — lihat Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add, atau file mcp-config.json yang disimpannya di direktori home Anda | mcpServers |
| Antigravity | file mcp_config.json yang dapat diakses dari pengaturannya | mcpServers |
| Windsurf | file mcp_config.json yang dapat diakses dari pengaturannya | mcpServers |
| Cline | pengaturan MCP-nya, yang didukung oleh file cline_mcp_settings.json | mcpServers |
Setiap klien dalam tabel itu kecuali empat klien yang memiliki bagian tersendiri di bawah menerima entri persis seperti yang tertulis di atas, di path pada barisnya. Klien yang tidak tercantum terhubung dengan cara yang sama jika membaca daftar server dalam salah satu bentuk ini.
Catatan tentang PATH
Klien yang dijalankan dari lingkungan grafis tidak selalu mewarisi PATH yang sama dengan terminal Anda. Jika klien melaporkan bahwa ia tidak dapat menemukan perintah aggrega, ganti "command": "aggrega" dengan path absolut ke binary (misalnya "command": "/home/you/.local/bin/aggrega", lokasi instalasi di Linux untuk pengguna bernama you). Selebihnya tetap sama.
Visual Studio Code
Visual Studio Code menyimpan server-servernya di bawah servers, bukan mcpServers, dan setiap entri menyebutkan transport yang digunakannya:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex menyimpan server-servernya dalam TOML, bukan JSON — di ~/.codex/config.toml untuk setiap proyek, atau di .codex/config.toml untuk satu proyek yang dipercaya Codex — masing-masing sebagai tabel yang dinamai sesuai server:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]codex mcp add aggrega -- aggrega mcp, perintah di atas, menulis tabel yang sama untuk Anda. Ekstensi IDE Codex dan aplikasi desktop ChatGPT membaca file yang sama, sehingga satu entri melayani ketiganya.
Zed
Zed menyimpan server-servernya di bawah context_servers dalam file pengaturannya. Tambahkan server dari Settings → AI → MCP Servers — Add Server, lalu Add Local Server — yang menulis entri ke file itu, atau jalankan zed: open settings file dari palet perintah dan tambahkan entri sendiri:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed mendukung tool dan prompt dari protokol, sehingga agennya menjangkau tool dan prompt penulisan Aggrega tetapi tidak menjangkau resource yang juga ditawarkan server.
Claude Desktop
Claude Desktop menginstal server lokal dari paket ekstensi — server beserta manifest yang mendeskripsikannya, dibundel menjadi satu file yang dapat diinstal dan ditambahkan dari pengaturan ekstensinya — bukan dari entri dalam file konfigurasi. Setiap rilis Aggrega menyertakan paket semacam itu, aggrega-<version>.mcpb, di samping binary siap pakainya.
Paket Aggrega tidak membawa program sendiri. Paket ini menjalankan executable aggrega yang sudah terinstal di mesin Anda, dengan satu argumen mcp, dan berkomunikasi dengan protokol melalui input dan output standar proses tersebut — server yang sama yang dijalankan setiap entri di atas. Kecuali Anda memilih executable lain, paket ini menyerahkan nama perintah aggrega kepada Claude Desktop, seperti yang dilakukan setiap entri di atas, sehingga aplikasi mencari aggrega di PATH yang digunakan saat aplikasi itu dimulai; dan paket ini menyerahkan workspace yang Anda pilih kepada server tersebut. Untuk menambahkannya:
- Instal binary
aggrega, seperti dijelaskan di Menginstal binary. Perintah instalasi dan langkah manual di sana sama-sama menyimpannya di folder milik Anda sendiri — di Windows%LOCALAPPDATA%\Programs\aggrega, bukan folder sistem sepertiC:\Windows\System32— agar Anda dapat menggantinya tanpa hak administrator. - Instal
aggrega-<version>.mcpbdari pengaturan ekstensi Claude Desktop. - Tetapkan pengaturan paket tersebut; tidak ada yang wajib. Path to the aggrega executable adalah program yang dijalankan paket, dan nilai default-nya adalah nama perintah
aggrega, yang dicari aplikasi diPATHyang digunakan saat aplikasi itu dimulai. Folder yang ditambahkan kePATHAnda saat aplikasi berjalan — seperti yang dilakukan installer Windows dan perintah instalasi di Windows dengan folder masing-masing — baru sampai ke aplikasi setelah aplikasi ditutup dan dimulai lagi, seperti pada langkah 4, dan aplikasi yang dimulai dari lingkungan grafis mungkin tidak melihatPATHyang sama dengan terminal Anda (lihat Catatan tentangPATH). Biarkan nilai default jikaaggregadiPATHtersebut adalah executable yang Anda inginkan. Sebaliknya, tetapkan kolom ke path lengkap sebuah executable jika executable yang Anda inginkan tidak ada diPATHtersebut, atau merupakanaggregayang berbeda dari yang pertama ditemukan di sana — di macOS dan Linux, untuk lokasi instalasi,aggregadi.local/bindalam folder home Anda, misalnya/Users/you/.local/bin/aggrega; di Windows, path lengkap yang berakhiranaggrega.exe, misalnyaC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Untuk kembali ke default, tetapkan kolom keaggregaalih-alih mengosongkannya. Jikaaggregasama sekali belum terinstal, instal seperti yang dijelaskan langkah 1. Workspace folder adalah folder workspace Aggrega tempat asisten bekerja: folder yang berisi.aggrega-config.yamlproyek Anda. Tetapkan yang satu ini: pengaturan ini kosong sampai Anda memilih folder, dan selama kosong, paket menyerahkanAGGREGA_WORKSPACE_ROOTyang kosong kepada server, sehingga server menjawab setiap permintaan yang dibuat asisten di workspace dengan penolakan yang menyatakan bahwa pengaturan Workspace folder kosong dan meminta Anda menetapkannya ke folder yang berisi.aggrega-config.yamlworkspace Anda, alih-alih bekerja di folder tempat Claude Desktop menjalankannya. Paket menyerahkan folder ke server hanya saat aplikasi menjalankan server, sehingga folder yang Anda tetapkan saat server berjalan baru berlaku setelah Anda menonaktifkan dan mengaktifkan kembali ekstensi di pengaturan ekstensi, atau memulai ulang aplikasi seperti pada langkah 4. - Tutup Claude Desktop sepenuhnya, lalu jalankan lagi. Server yang sudah dijalankan aplikasi tetap berjalan, dan mengganti nama executable tidak menghentikannya, sehingga pengaturan yang diubah baru berlaku setelah aplikasi menjalankan server lagi: setelah aplikasi ditutup dan dijalankan lagi, atau, untuk Workspace folder, setelah ekstensi dinonaktifkan dan diaktifkan kembali. Di Windows, Task Manager menunjukkan apakah proses
aggregamasih berjalan.
Folder workspace adalah tempat setiap permintaan yang tidak menyebutkan workspace sendiri dijawab. Claude Desktop menjalankan server di folder pilihannya sendiri, bukan di proyek Anda, sehingga paket meneruskan folder yang Anda pilih ke server sebagai variabel AGGREGA_WORKSPACE_ROOT di lingkungannya, bukan sebagai argumen pada baris perintah yang disusun aplikasi. Server mengambil folder itu sebagai root workspace itu sendiri, sebagaimana --workspace-root diambil pada setiap perintah: server tidak mencari workspace yang melingkupinya di atas folder itu, jadi pilih folder yang berisi .aggrega-config.yaml, bukan folder di dalamnya. Untuk bekerja di workspace lain, ubah pengaturan dan mulai ulang aplikasi seperti pada langkah 4. Pada permintaan yang menyebutkan workspace sendiri dengan workspace_root relatif, path itu juga dibaca dari folder workspace, sehingga prompt dapat menyebutkan folder di dalamnya — misalnya quickstart-ai/1 — tanpa mengetahui letak folder itu di mesin Anda; workspace_root absolut digunakan sebagaimana diberikan. Selama pengaturan kosong, path relatif dijawab dengan penolakan yang sama seperti permintaan yang tidak menyebutkan workspace apa pun.
Karena paket tidak menyebutkan executable dari platform mana pun, file yang sama berlaku untuk setiap platform yang dideklarasikannya: macOS, Windows, dan Linux.
Server melaporkan aggrega mana yang dijalankan paket. Pengaturan ekstensi Claude Desktop mencantumkan versi paket itu sendiri — versi rilis asalnya — dan bukan versi executable yang dijalankannya. Keduanya diinstal secara terpisah, sehingga dapat berasal dari rilis yang berbeda. Paket menyerahkan versinya sendiri kepada server sebagai variabel AGGREGA_BUNDLE_VERSION di lingkungannya, dan server melaporkan keduanya: jawaban describe-capabilities yang dipanggil tanpa argumen — tool yang dipanggil asisten untuk mengetahui apa yang ditawarkan server — diawali dengan baris yang menyebutkan versi executable dan versi paket, dan membawa baris yang sama sebagai version_summary di bagian terstrukturnya, sehingga asisten yang ditanya versi Aggrega mana yang sedang berjalan dapat membaca keduanya di sana, bagian mana pun dari jawaban yang diserahkan aplikasi kepadanya. Jika keduanya berasal dari rilis yang berbeda, baris itu menyatakannya, dengan menyebutkan keduanya, dan panduan yang diserahkan server kepada asisten saat terhubung diawali dengan kalimat yang sama. Tidak ada penolakan karena perbedaan, dan server menjawab setiap permintaan seperti biasa; hal ini dilaporkan agar Anda tahu executable mana yang dijalankan paket. Untuk menyamakan keduanya, instal aggrega-<version>.mcpb dari rilis asal executable Anda — aggrega version di terminal mencetak versi itu — atau tetapkan Path to the aggrega executable ke path lengkap sebuah aggrega dari rilis paket, lalu mulai ulang aplikasi seperti pada langkah 4.
Log Claude Desktop sendiri menunjukkan apa yang dijalankannya. Di Windows, log dapat berada di bawah folder paket di direktori data aplikasi lokal, bukan di bawah %APPDATA%\Claude\logs, bahkan jika Claude Desktop diinstal dari unduhannya sendiri: di bawah %LOCALAPPDATA%\Packages\, di folder yang namanya diawali Claude_, di LocalCache\Local\Claude\logs. File di sana mencakup mcp.log dan mcp-server-Aggrega.log, dengan file kedua memuat apa yang ditulis server Aggrega ke standard error-nya. Baris yang memuat Using MCP server command: menyebutkan perintah yang dijalankan aplikasi, yang diambil dari pengaturan Path to the aggrega executable paket. Jika pengaturan tersebut menyebutkan path yang tidak berisi apa pun, log memuat pesan interpreter perintah Windows bahwa path tersebut tidak dikenali sebagai perintah, lalu melaporkan bahwa server tidak dapat dimulai. Jika folder workspace tidak ada — diganti namanya, dipindahkan, atau tidak pernah dibuat — server tetap dimulai dan menjawab setiap permintaan yang dibuat asisten di workspace itu dengan penolakannya, sehingga asisten menerima penolakan sebagai jawaban atas permintaannya, alih-alih aplikasi melaporkan kegagalan koneksi. Penolakan itu menyebutkan AGGREGA_WORKSPACE_ROOT sebagai variabel yang ditetapkan oleh pengaturan Workspace folder paket, dan mengutip folder persis seperti yang diteruskan aplikasi; mcp-server-Aggrega.log memuat penolakan yang sama. Workspace folder yang dibiarkan kosong dijawab dengan cara yang sama, dengan penolakan dari langkah 3 yang menyebutkan pengaturan yang kosong, yang juga dimuat log. Perbaiki pengaturan dan mulai ulang aplikasi seperti pada langkah 4.
Pengaturan konektor Claude Desktop adalah jalur lainnya, untuk server yang dijangkau melalui HTTPS: lihat Server yang dijangkau melalui HTTPS.
Ketika klien tidak menerima seluruh permukaan tool
Aggrega mengumumkan seluruh permukaan tool-nya dan menyerahkan kepada klien seberapa banyak yang akan disajikan kepada model. Beberapa klien membatasi jumlah tool yang mereka daftarkan sekaligus dan membuang sisanya. Jika itu terjadi, mcp.announce_tools mempersingkat apa yang diumumkan server menjadi tool yang Anda sebutkan — lihat Mempersempit apa yang diumumkan server.
Server yang dijangkau melalui HTTPS
Setiap entri di atas menjalankan server sendiri. Server yang dijalankan orang lain — satu proses berumur panjang di sebuah host, yang melayani satu workspace — dijangkau melalui jaringan, dan entrinya menyebutkan alamat, bukan perintah:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}Path-nya selalu /mcp; host-nya adalah apa pun yang dipublikasikan operator untuk server tersebut. Mintalah kepada mereka. Gemini CLI menerima alamat di bawah httpUrl, bukan url: ia membaca url sebagai server pada transport event-stream yang lebih lama, dan httpUrl sebagai server pada transport HTTP yang dapat di-stream, yaitu transport yang digunakan server ini.
Klien Anda yang memperoleh token, bukan Anda. Tidak ada hal tentang login yang dikonfigurasi dalam entri: server menjawab permintaan yang tidak diautentikasi dengan menyebutkan dokumen yang menyatakan server otorisasi mana yang menerbitkan tokennya, dan klien yang mendukung alur otorisasi protokol membaca dokumen itu, mengarahkan Anda untuk login, dan melampirkan token yang diterimanya ke setiap permintaan berikutnya. Nama scope yang dapat dimintanya dipublikasikan dalam dokumen yang sama. Klien yang tidak mengimplementasikan alur tersebut tidak dapat menjangkau server jenis ini, dan tidak ada yang Anda tambahkan ke entri yang dapat menggantikannya.
Tool yang tidak terjangkau oleh scope login Anda tetap ada di daftar tool. Pemanggilannya ditolak, dengan menyebutkan scope yang akan mengizinkannya, dan klien yang mengimplementasikan step-up protokol menjawab penolakan itu dengan meminta Anda login lagi untuk scope tersebut. Klien yang tidak melakukan step-up tetap dapat diberi scope tulis: siapa pun yang menjalankan server otorisasi menjadikannya scope default untuk klien itu, sehingga login pertamanya sudah membawanya — dengan konsekuensi bahwa setiap login melalui klien itu kemudian membawa akses tulis. Apa yang dapat dijangkau pemanggil menjelaskan apa yang diizinkan setiap scope, dan bagaimana pengaturan itu berperilaku untuk klien yang mendaftarkan dirinya ulang setiap kali terhubung.
Apa yang dibutuhkan server semacam itu, dan apa yang dikonfigurasi oleh operatornya, dijelaskan di halaman aggrega mcp dalam referensi.
Memverifikasi koneksi
Setelah klien terhubung kembali, pastikan integrasi aktif: klien seharusnya mencantumkan prompt penulisan Aggrega (satu untuk masing-masing peran pengembang, arsitek, dan operasi, ditambah templat per entitas) dan tool penulisan — di antaranya scaffold, validate, describe, dan get-schema. Minta asisten membuat kerangka sebuah komponen, dan asisten seharusnya mengembalikan kerangka yang memuat field yang diwajibkan sebuah Component. Jika tidak ada yang muncul, periksa bahwa aggrega version berjalan dari terminal dan bahwa command klien mengarah ke binary — catatan tentang PATH di atas mencakup penyebab yang umum.