Dokümantasyon / Entegrasyonlar

MCP sunucuları

Uzmanlara MCP sunucularının araçları verilebilir. Sunucular tek bir dosyada tanımlanır; her kayıtta o sunucunun araçlarını hangi uzmanların alacağı yazar.

ivralo'da MCP

MCP (Model Context Protocol), bir programın modele araç sunmasının standart yoludur: bir issue takip sisteminde arama, bir wiki'nin sayfaları, bir sohbetin mesajları gibi. ivralo tanımladığınız MCP sunucularına bağlanır ve araçlarını yalnızca belirttiğiniz uzmanlara verir. Diğer uzmanlar bu araçları almaz; böylece her uzmanın araç listesi kısa kalır.

mcp.json

Sunucular ana dizininizdeki mcp.json dosyasında tanımlanır. Başka bir dosya kullanmak için IVRALO_MCP_CONFIG'i ayarlayın.

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": { "API_KEY": "${EVERYTHING_KEY}" },
      "agents": ["analyst"],
      "timeout_seconds": 30
    },
    "wiki": {
      "url": "https://wiki.example.com/mcp",
      "headers": { "Authorization": "Bearer ${WIKI_TOKEN}" },
      "agents": ["librarian"]
    }
  }
}

Temel alanlar diğer MCP istemcilerinin kullandıklarıyla aynıdır; bir MCP sunucusunun README'sindeki sunucu bloğunu doğrudan yapıştırabilirsiniz. ivralo'ya özel alanlar da aynı blokta yer alır.

Anahtar	Neyi belirler
`command`, `args`	süreç olarak başlatılan yerel bir sunucu; `args` bir string listesidir
`url`	uzak bir sunucunun adresi
`transport` (ya da `type`)	`stdio`, `sse` ya da `streamable-http`; `http` de kabul edilir
`env`	yerel sunucu için ortam değişkenleri
`headers`	uzak sunucu için HTTP başlıkları
`agents`	sunucunun araçlarını alacak preset anahtarları
`enabled`	`false` verilirse kayıt dosyada kalır ama kimseye bağlanmaz
`timeout_seconds`	okuma zaman aşımı; varsayılan 30
`include_tools`, `exclude_tools`	yalnızca belirli araçları açar ya da bazılarını gizler
`tool_name_prefix`	ad çakışmalarına karşı araç adlarına eklenen önek

Her kayıtta command ya da url'den yalnızca biri bulunur. Transport'un varsayılanı komut için stdio, URL için streamable-http'dir; başka bir transport'la verilen komut reddedilir. Bilinmeyen bir anahtar sessizce yok sayılmaz, sorun olarak bildirilir; aksi halde bir yazım hatası sunucunun davranışını fark ettirmeden değiştirebilirdi.

Gizli değerler ortamda kalır

env, headers ve url içindeki ${VAR} yer tutucuları dosya yüklenirken ortamdan doldurulur. Değerin kendisi mcp.json'da değil, .env dosyanızda durur. Sunucu kapalı değilse, değişkeni tanımlı olmayan bir yer tutucu sorun olarak bildirilir.

Her sunucu için agents listesi

agents, o sunucunun yetkisidir. Preset'leri anahtarlarıyla listeler: analyst, librarian, coder ya da local bir skill'le gelen bir uzman. Her anahtar ekiple karşılaştırılır; bilinmeyen bir anahtar, geçerli anahtarları sıralayan bir sorun olarak bildirilir.

Bazı ajanlar, dosyada ne yazarsa yazsın, hiçbir zaman MCP aracı almaz:

Kim	Neden
ana ajan	`main`, `agents`'ın kabul ettiği bir anahtar değildir
strict profilindeki her ajan	`IVRALO_PROFILE=strict` dışarıya uzanan bütün yetkileri kaldırır ve bir sunucunun nereye eriştiği ivralo'nun içinden değerlendirilemez
soru cevaplayan bir instance	yalnızca okuma yapar; bir sunucunun araçlarının ne yaptığından kimse emin olamaz
replay	sunucu, kayıtlı çağrılardan önce, çalıştırmanın başında bağlanır

Yan bir iş için açılan instance, yalnızca onu açan ajanın sahip olduğu sunuculara erişir.

Bozuk bir kayıt kurulumu durdurur

Listeleme hatalara karşı esnektir: ivralo mcp list sağlam kayıtları gösterir ve bütün sorunları tek tek sayar. Ekibin kurulması ise esnek değildir. mcp.json'da herhangi bir sorun varsa ekip, uzmanları sandığınızdan az araçla başlatmak yerine sorunu belirterek kurulmayı reddeder. ivralo doctor bağlanmadan bütün sorunları listeler.

Çalışma sırasında sunuculara her çalıştırmanın başında bağlanılır. O anda bağlanılamayan sunucu hata vermez, bir log satırı yazılarak atlanır. Bu yüzden yeni bir kayda güvenmeden önce onu test edin:

ivralo mcp test everything

Bu komut sunucuya gerçekten bağlanır, araçlarını listeler; bağlanamazsa nedenini yazar ve 1 ile çıkar.

Sunucu eklemek

ivralo mcp add everything --command npx --arg -y --arg @modelcontextprotocol/server-everything --agent analyst
ivralo mcp add wiki --url https://wiki.example.com/mcp --header 'Authorization=Bearer ${WIKI_TOKEN}' --agent librarian

Seçenek	Neyi belirler
`--command`, `--arg`	yerel bir sunucu; `--arg` birden fazla kez verilebilir ve olduğu gibi, bölünmeden saklanır
`--url`, `--transport`	uzak bir sunucu
`--env KEY=VALUE`, `--header KEY=VALUE`	birden fazla kez verilebilir; `${VAR}` açılır
`--agent`, `-a`	sunucuyu alacak preset; birden fazla kez verilebilir
`--timeout`	saniye cinsinden okuma zaman aşımı
`--include-tool`, `--exclude-tool`	birden fazla kez verilebilir
`--prefix`	araç adı öneki
`--disabled`	kaydı dosyada tutar, kimseye bağlamaz
`--yes`	mevcut bir kaydın üzerine sormadan yazar

ivralo mcp remove <ad> bir kaydı siler; --yes verilmediyse önce onay ister.

Tarifler

En çok istenen sunucuları tek komutla ekleyebilirsiniz:

ivralo mcp recipes
ivralo mcp add --recipe linear

Tarif	Ne sağlar	Ne gerektirir	Kime verilir
`github`	issue'lar, pull request'ler, dosyalar, kod arama; resmî Docker imajıyla	`GITHUB_PERSONAL_ACCESS_TOKEN`	`analyst`
`slack`	kanallar, mesajlar, kullanıcılar	`SLACK_BOT_TOKEN`, `SLACK_TEAM_ID`	`analyst`
`notion`	sayfalar ve veritabanları	`NOTION_TOKEN`	`librarian`
`atlassian`	Jira issue'ları, Confluence sayfaları	ilk kullanımda tarayıcıdan giriş	`analyst`
`linear`	issue'lar, projeler, döngüler	ilk kullanımda tarayıcıdan giriş	`analyst`

Tarif her gizli değeri bir ${VAR} yer tutucusu olarak yazar ve tanımlamanız gereken değişkenleri ekrana basar. Hosted sunuculara mcp-remote üzerinden bağlanılır; o da girişi tarayıcıdan yapar ve token'ı kendi saklama alanında tutar. Önerilen preset'i --agent ile değiştirebilirsiniz. Sıradan GitHub işleri için Docker gerektirmeyen yerleşik GitHub Clerk var.

Windows'ta npx ile başlatılan sunucuların cmd /c npx -y ... biçiminde yazılması gerekir; tarifler bunu sizin için böyle yazar. args içindeki yollarda düz eğik çizgi (/) kullanmak en güvenlisidir.