MCP sunucusunu bağlama
Aggrega’nın MCP sunucusu aggrega mcp komutudur ve tek ön koşulu aggrega ikili dosyasıdır: İkili dosyayı kurun onu tek bir komutla kurar. Sunucu istemcinizin bir alt süreci olarak stdio üzerinden çalışır, şemalarını ikili dosyadan, belge sayfalarını ise makinenizin önbelleğine bir kez getirdiği bir kopyadan okur ve ayrı bir hizmete, porta veya hesaba ihtiyaç duymaz. Sizin için zaten başka biri bir sunucu çalıştırıyorsa ne ikili dosyaya ne de bunların hiçbirine ihtiyacınız vardır: bkz. HTTPS üzerinden erişilen bir sunucu.
Tek bir komutla ekleyen istemciler
Aggrega eklentisi yüklü bir asistan zaten bağlıdır. Eklentiyi yüklemek, Aggrega becerisini ve sunucuyu tek adımda ekler — Eklentiyi yükleme sayfasında açıklandığı gibi Claude Code, Codex, GitHub Copilot, Gemini CLI, Antigravity, Cursor, Kiro ve OpenClaw’da — bu nedenle o asistanı bağlamak için bu sayfadaki başka hiçbir şeye gerek yoktur. Eklenti aggrega mcp komutunu, asistanın başlatıldığı PATH üzerinde bulunan aggrega ile başlatır; bu nedenle ikili dosyanın orada yüklü olması gerekir. Bazı asistanlar bir eklentinin sunucusunu projeniz yerine eklentinin kendi klasöründe başlatır — Codex böyle yapar — ve asistan bu durumda, bunu kabul eden çağrılarda projenizin klasörünü workspace_root olarak belirtir; beceri, asistana sunucunun hangi çalışma alanında yanıt verdiğini denetlemesini söyler.
Eklenti olmadan, sunucuyu istemcinin kendi komutuyla ekleyin. Claude Code’da:
claude mcp add --transport stdio aggrega -- aggrega mcpCodex’te:
codex mcp add aggrega -- aggrega mcpGemini CLI’da:
gemini mcp add aggrega aggrega mcpDiğer tüm istemciler
MCP destekleyen istemcilerin çoğu sunucuyu aynı şekilde başlatır: aggrega komutunu tek bir mcp argümanıyla çalıştırır ve protokolü sürecin standart girdisi ve çıktısı üzerinden konuşur. Aralarındaki fark, her birinin sunucu listesini nerede tuttuğu ve listedeki girdilere ne ad verdiğidir. Ortak biçim:
{ "mcpServers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}İstemci yeniden başlayıp bağlandığında Aggrega yazım istemleri, kaynakları ve araçları kullanılabilir hâle gelir. Asistanınızın Aggrega ile yapabilecekleri bunları açıklar, Aggrega dosyalarını yazma bunlarla ne yapılacağını gösterir, aggrega mcp başvurusu ise komutun kendisini ele alır.
Girdideki hiçbir şey bir protokol sürümü seçmez. Aggrega, standart girdi ve çıktı üzerinde de HTTPS üzerinden de hem 2026-07-28 hem 2025-06-18 sürümünü konuşur; bu nedenle ikisinden birini kullanan bir istemci bağlanır ve aynı istemlere, kaynaklara ve araçlara ulaşır. Bir istemcinin hangisini istediği yapılandırmanızda değil, bağlantı üzerinde belirlenir.
Komut çalıştırabilen bir asistan bunların hepsini kendisi yapabilir — ikili dosyayı kurmak, Aggrega becerisini eklemek ve sunucuya bağlanmak — ona yapıştırdığınız tek bir istemle: bkz. Aggrega’yı yapay zekâ asistanınızla kurma.
Her istemcinin sunucu listesini tuttuğu yer
| İstemci | Listenin bulunduğu yer | Girdinin adı |
|---|---|---|
| Claude Code | claude mcp add ya da projedeki bir .mcp.json dosyası | mcpServers |
| Claude Desktop | yerel bir sunucu için uzantı ayarları; HTTPS üzerinden erişilen bir sunucu için bağlayıcı ayarları | bkz. Claude Desktop |
| Cursor | tek bir çalışma alanı için .cursor/mcp.json ya da tüm çalışma alanları için kullanıcı kapsamlı bir mcp.json | mcpServers |
| Gemini CLI | gemini mcp add veya tüm projeler için ~/.gemini/settings.json ve tek bir proje için .gemini/settings.json | mcpServers |
| Codex CLI | codex mcp add veya tüm projeler için ~/.codex/config.toml ve güvenilen tek bir proje için .codex/config.toml | bir [mcp_servers.aggrega] tablosu — bkz. Codex CLI |
| Zed | Settings → AI → MCP Servers; girdiyi Zed’in ayar dosyasına yazar | context_servers — bkz. Zed |
| Visual Studio Code | kullanıcı profilinizdeki mcp.json ya da tek bir çalışma alanı için .vscode/mcp.json | servers — bkz. Visual Studio Code |
| GitHub Copilot CLI | copilot mcp add ya da ana dizininizde tuttuğu mcp-config.json dosyası | mcpServers |
| Antigravity | ayarlarından erişilebilen mcp_config.json dosyası | mcpServers |
| Windsurf | ayarlarından erişilebilen mcp_config.json dosyası | mcpServers |
| Cline | bir cline_mcp_settings.json dosyasına dayanan MCP ayarları | mcpServers |
Aşağıda kendi bölümü olan dördü dışında, tablodaki her istemci girdiyi tam olarak yukarıda yazıldığı gibi, kendi satırındaki yolda kabul eder. Listede olmayan bir istemci, bu biçimlerden birinde bir sunucu listesi okuyorsa aynı şekilde bağlanır.
PATH hakkında bir not
Grafik bir ortamdan başlatılan istemciler her zaman terminalinizle aynı PATH değerini devralmaz. Bir istemci aggrega komutunu bulamadığını bildirirse "command": "aggrega" yerine ikili dosyanın mutlak yolunu yazın (örneğin "command": "/home/you/.local/bin/aggrega"; bu, Linux’ta you adlı bir kullanıcı için kurulum konumudur). Geri kalan her şey aynı kalır.
Visual Studio Code
Visual Studio Code sunucularını mcpServers yerine servers altında tutar ve her girdi kullandığı aktarımı belirtir:
{ "servers": { "aggrega": { "type": "stdio", "command": "aggrega", "args": ["mcp"] } }}Codex CLI
Codex sunucularını JSON yerine TOML’da tutar — tüm projeler için ~/.codex/config.toml içinde veya Codex’in güvendiği tek bir proje için .codex/config.toml içinde — her birini sunucunun adını taşıyan bir tablo olarak:
[mcp_servers.aggrega]command = "aggrega"args = ["mcp"]Yukarıdaki komut olan codex mcp add aggrega -- aggrega mcp, aynı tabloyu sizin için yazar. Codex IDE uzantısı ve ChatGPT masaüstü uygulaması aynı dosyayı okur, bu nedenle tek girdi üçüne de hizmet eder.
Zed
Zed sunucularını ayar dosyasında context_servers altında tutar. Sunucuyu Settings → AI → MCP Servers üzerinden — Add Server, ardından Add Local Server — ekleyin; bu, girdiyi o dosyaya yazar. Ya da komut paletinden zed: open settings file çalıştırıp girdiyi kendiniz ekleyin:
{ "context_servers": { "aggrega": { "command": "aggrega", "args": ["mcp"] } }}Zed, protokolün araçlarını ve istemlerini destekler; bu nedenle aracısı Aggrega’nın araçlarına ve yazım istemlerine ulaşır, ancak sunucunun ayrıca sunduğu kaynaklara ulaşmaz.
Claude Desktop
Claude Desktop yerel bir sunucuyu bir yapılandırma dosyasındaki girdiden değil, bir uzantı paketinden kurar: sunucu ve onu tanımlayan bir manifest, tek bir kurulabilir dosyada bir araya getirilir ve uzantı ayarlarından eklenir. Her Aggrega sürümü, önceden derlenmiş ikili dosyalarının yanında böyle bir paket, aggrega-<version>.mcpb, taşır.
Aggrega’nın paketi kendine ait bir program taşımaz. Makinenizde zaten kurulu olan bir aggrega yürütülebilir dosyasını tek mcp argümanıyla başlatır ve protokolü o sürecin standart girdisi ve çıktısı üzerinden konuşur; bu, yukarıdaki her girdinin başlattığı sunucunun aynısıdır. Başka bir yürütülebilir dosya seçmediğiniz sürece, yukarıdaki her girdinin yaptığı gibi Claude Desktop’a aggrega komut adını iletir, böylece uygulama aggrega dosyasını başlatıldığı PATH üzerinde arar; ve sunucuya seçtiğiniz çalışma alanını iletir. Eklemek için:
aggregaikili dosyasını İkili dosyayı kurun bölümünde anlatıldığı gibi kurun. Oradaki kurulum komutu da elle yapılan adımlar da onu size ait bir klasörde tutar — Windows’taC:\Windows\System32gibi bir sistem klasörü yerine%LOCALAPPDATA%\Programs\aggrega— böylece dosyayı yönetici hakları olmadan değiştirebilirsiniz.aggrega-<version>.mcpbpaketini Claude Desktop’ın uzantı ayarlarından kurun.- Paketin ayarlarını belirleyin; hiçbiri zorunlu değildir. Path to the aggrega executable, paketin başlattığı programdır ve varsayılan değeri
aggregakomut adıdır; uygulama bunu başlatıldığıPATHüzerinde arar. Uygulama çalışırkenPATHdeğişkeninize eklenen bir klasör (Windows yükleyicisi ve Windows’taki kurulum komutu kendi klasörlerini bu şekilde ekler), 4. adımdaki gibi uygulama kapatılıp yeniden başlatılana kadar uygulamaya ulaşmaz; ayrıca grafik ortamdan başlatılan bir uygulama, terminalinizle aynıPATHdeğerini görmeyebilir (bkz.PATHhakkında bir not). OPATHüzerindekiaggregaistediğiniz yürütülebilir dosyaysa varsayılanı olduğu gibi bırakın. İstediğiniz dosya oPATHüzerinde değilse ya da orada bulunan ilkaggregadosyasından farklıysa, alanı bunun yerine bir yürütülebilir dosyanın tam yoluna ayarlayın — macOS ve Linux’ta, kurulum konumu için ana klasörünüzdeki.local/biniçindekiaggrega, örneğin/Users/you/.local/bin/aggrega; Windows’taaggrega.exeile biten tam yol, örneğinC:\Users\you\AppData\Local\Programs\aggrega\aggrega.exe. Varsayılana dönmek için alanı boşaltmak yerineaggregaolarak ayarlayın. Hiçaggregakurulu değilse, 1. adımda anlatıldığı gibi kurun. Workspace folder, asistanın içinde çalıştığı Aggrega çalışma alanının klasörüdür: projenizin.aggrega-config.yamldosyasını barındıran klasör. Bunu belirleyin: siz bir klasör seçene kadar boştur ve boş olduğu sürece paket sunucuya boş birAGGREGA_WORKSPACE_ROOTiletir; bu yüzden sunucu, Claude Desktop’ın kendisini başlattığı klasörde çalışmak yerine, asistanın çalışma alanında yaptığı her isteği, Workspace folder ayarının boş olduğunu söyleyen ve onu çalışma alanınızın.aggrega-config.yamldosyasını barındıran klasöre ayarlamanızı isteyen bir retle yanıtlar. Paket klasörü sunucuya yalnızca uygulama sunucuyu başlattığında iletir; bu nedenle sunucu çalışırken ayarladığınız bir klasör, uzantıyı uzantı ayarlarında kapatıp yeniden açtığınızda ya da uygulamayı 4. adımdaki gibi yeniden başlattığınızda etkili olur. - Claude Desktop’tan tamamen çıkın, ardından yeniden başlatın. Uygulamanın daha önce başlattığı bir sunucu çalışmaya devam eder ve yürütülebilir dosyayı yeniden adlandırmak onu durdurmaz; bu nedenle değiştirilen bir ayar ancak uygulama sunucuyu yeniden başlattığında etkili olur: uygulama kapanıp yeniden başladığında ya da Workspace folder için uzantı kapatılıp yeniden açıldığında. Windows’ta Görev Yöneticisi, bir
aggregasürecinin hâlâ çalışıp çalışmadığını gösterir.
Çalışma alanı klasörü, kendi çalışma alanını belirtmeyen her isteğin yanıtlandığı yerdir. Claude Desktop sunucuyu projenizde değil, kendi seçtiği bir klasörde başlatır; bu nedenle paket, seçtiğiniz klasörü sunucuya uygulamanın oluşturduğu komut satırında bir argüman olarak değil, ortamındaki AGGREGA_WORKSPACE_ROOT değişkeni olarak iletir. Sunucu bu klasörü, --workspace-root her komutta nasıl alınıyorsa öyle, doğrudan çalışma alanı kökü olarak alır: kapsayan bir çalışma alanı için üst dizinlere bakmaz; bu yüzden içindeki bir klasörü değil, .aggrega-config.yaml dosyasını barındıran klasörü seçin. Başka bir çalışma alanında çalışmak için ayarı değiştirin ve uygulamayı 4. adımdaki gibi yeniden başlatın. Göreli bir workspace_root ile kendi çalışma alanını belirten bir istekte bu yol da çalışma alanı klasörüne göre okunur; böylece bir istem, klasörün makinenizde nerede durduğunu bilmeden içindeki bir klasörü — örneğin quickstart-ai/1 — belirtir; mutlak bir workspace_root verildiği gibi kullanılır. Ayar boş olduğu sürece göreli bir yol da hiçbir çalışma alanı belirtmeyen bir istekle aynı retle yanıtlanır.
Paket hiçbir platformun yürütülebilir dosyasını belirtmediğinden, aynı dosya bildirdiği her platformda geçerlidir: macOS, Windows ve Linux.
Sunucu, paketin hangi aggrega dosyasını başlattığını bildirir. Claude Desktop’ın uzantı ayarları, paketin başlattığı yürütülebilir dosyanın sürümünü değil, paketin kendi sürümünü, yani geldiği sürümün numarasını listeler. İkisi ayrı ayrı kurulduğundan farklı sürümlerden gelebilirler. Paket kendi sürümünü sunucuya ortamındaki AGGREGA_BUNDLE_VERSION değişkeni olarak iletir ve sunucu ikisini de bildirir: argümansız çağrılan describe-capabilities aracının (bir asistanın sunucunun neler sunduğunu öğrenmek için çağırdığı araç) yanıtı, yürütülebilir dosyanın ve paketin sürümünü belirten bir satırla başlar ve aynı satırı yapılandırılmış bölümünde version_summary olarak taşır; böylece hangi Aggrega sürümünün çalıştığı sorulan bir asistan, uygulama yanıtın hangi bölümünü iletirse iletsin, ikisini de orada okuyabilir. İkisi farklı sürümlerden geldiğinde bu satır bunu, her ikisini de belirterek söyler ve sunucunun bağlanırken asistana ilettiği yönergeler de aynı cümleyle başlar. Bir farklılık nedeniyle hiçbir şey reddedilmez ve sunucu her isteği her zamanki gibi yanıtlar; bu bilgi, paketin hangi yürütülebilir dosyayı çalıştırdığını bilmeniz için bildirilir. İkisini eşitlemek için, yürütülebilir dosyanızın geldiği sürümün aggrega-<version>.mcpb paketini kurun (bir terminalde aggrega version bu sürümü yazdırır) ya da Path to the aggrega executable ayarını paketin sürümüne ait bir aggrega dosyasının tam yoluna ayarlayın, ardından uygulamayı 4. adımdaki gibi yeniden başlatın.
Claude Desktop’ın kendi günlükleri neyi başlattığını gösterir. Windows’ta bu günlükler, Claude Desktop kendi indirmesinden kurulmuş olsa bile %APPDATA%\Claude\logs altında değil, yerel uygulama verileri dizinindeki bir paket klasörünün altında bulunabilir: %LOCALAPPDATA%\Packages\ altında, adı Claude_ ile başlayan klasörde, LocalCache\Local\Claude\logs konumunda. Buradaki dosyalar arasında mcp.log ve mcp-server-Aggrega.log bulunur; ikincisi Aggrega sunucusunun standart hataya yazdıklarını taşır. Using MCP server command: içeren bir satır, uygulamanın başlattığı komutu belirtir; bu komut paketin Path to the aggrega executable ayarından alınır. Ayar, hiçbir şeyin bulunmadığı bir yolu belirttiğinde günlük, Windows komut yorumlayıcısının yolun bir komut olarak tanınmadığını belirten iletisini taşır, ardından sunucunun başlatılamadığını bildirir. Çalışma alanı klasörü orada olmadığında (yeniden adlandırılmış, taşınmış ya da hiç oluşturulmamışsa) sunucu yine başlar ve asistanın o çalışma alanında yaptığı her isteği reddiyle yanıtlar; böylece uygulama bir bağlantı hatası bildirmek yerine asistan reddi isteğinin yanıtı olarak alır. Ret, AGGREGA_WORKSPACE_ROOT değişkenini paketin Workspace folder ayarının belirlediği değişken olarak adlandırır ve klasörü uygulamanın ilettiği biçimde aynen aktarır; mcp-server-Aggrega.log da aynı reddi taşır. Boş bırakılan bir Workspace folder da aynı şekilde, boş ayarı belirten 3. adımdaki retle yanıtlanır ve günlük bunu da taşır. Ayarı düzeltin ve uygulamayı 4. adımdaki gibi yeniden başlatın.
Claude Desktop’ın bağlayıcı ayarları, HTTPS üzerinden erişilen bir sunucu için diğer yoldur: bkz. HTTPS üzerinden erişilen bir sunucu.
Bir istemci araç yüzeyinin tamamını almadığında
Aggrega tüm araç yüzeyini duyurur ve bunun ne kadarının modele sunulacağına istemcinin karar vermesini bırakır. Bazı istemciler aynı anda kaydedecekleri araç sayısını sınırlar ve gerisini atar. Bu durumda mcp.announce_tools, sunucunun duyurduklarını belirttiğiniz araçlarla kısaltır; bkz. Sunucunun duyurduklarını daraltma.
HTTPS üzerinden erişilen bir sunucu
Yukarıdaki her girdi sunucuyu kendisi başlatır. Başka birinin çalıştırdığı bir sunucuya (bir ana makinede uzun süre çalışan ve tek bir çalışma alanına hizmet veren bir sürece) ise ağ üzerinden erişilir ve girdisi bir komut yerine bir adres belirtir:
{ "mcpServers": { "aggrega": { "url": "https://aggrega.example.com/mcp" } }}Yol her zaman /mcp’dir; ana makine ise operatörün o sunucu için yayımladığı adrestir. Bunu operatöre sorun. Gemini CLI adresi url altında değil httpUrl altında alır: url’yi eski olay akışı aktarımındaki bir sunucu, httpUrl’yi ise bu sunucunun konuştuğu akışlı HTTP aktarımındaki bir sunucu olarak okur.
Belirteci siz değil, istemciniz alır. Oturum açmayla ilgili hiçbir şey girdide yapılandırılmaz: sunucu, kimliği doğrulanmamış bir isteği, belirteçlerini hangi yetkilendirme sunucusunun verdiğini belirten belgeyi adlandırarak yanıtlar. Protokolün yetkilendirme akışını destekleyen bir istemci bu belgeyi okur, sizi oturum açmaya yönlendirir ve aldığı belirteci sonraki her isteğe ekler. İstemcinin isteyebileceği kapsam adları da aynı belgede yayımlanır. Bu akışı uygulamayan bir istemci bu türden bir sunucuya erişemez ve girdiye eklediğiniz hiçbir şey bu akışın yerini tutmaz.
Oturumunuzun kapsamlarının erişmediği bir araç yine de araç listesinde yer alır. Bu aracın çağrılması, ona erişim sağlayacak kapsamı belirten bir retle reddedilir. Protokolün step-up akışını uygulayan bir istemci bu redde, sizden o kapsam için yeniden oturum açmanızı isteyerek yanıt verir. Step-up yapmayan bir istemciye de yazma kapsamları verilebilir: yetkilendirme sunucusunu çalıştıran kişi bunları o istemci için varsayılan kapsamlar yapar; böylece istemcinin ilk oturum açması bu kapsamları zaten taşır. Bunun bedeli, o istemci üzerinden açılan her oturumun bundan sonra yazma erişimi taşımasıdır. Bir çağıranın nelere erişebileceği bölümü, her kapsamın neye erişim sağladığını ve bu ayarın, her bağlandığında kendini yeniden kaydeden bir istemci için nasıl davrandığını açıklar.
Böyle bir sunucunun neler gerektirdiği ve operatörünün neleri yapılandırdığı aggrega mcp başvurusunda yer alır.
Bağlantıyı doğrulayın
İstemci yeniden bağlandıktan sonra entegrasyonun etkin olduğunu doğrulayın: istemci, Aggrega yazım istemlerini (geliştirici, mimar ve operasyon rollerinin her biri için bir tane ve buna ek olarak varlık başına bir şablon) ve yazım araçlarını — aralarında scaffold, validate, describe ve get-schema bulunur — listelemelidir. Asistandan bir bileşen iskeleti oluşturmasını isteyin; asistan, bir Component’in gerektirdiği alanları içeren bir iskelet döndürmelidir. Hiçbir şey görünmüyorsa aggrega version komutunun bir terminalden çalıştığını ve istemcinin command değerinin ikili dosyayı gösterdiğini kontrol edin — yukarıdaki PATH notu yaygın nedeni açıklar.