Embassy (MCP Base)

Embassy ("elçilik"; uygulamada MCP Bases), müşterinin kendi ağında bir projenin yanında çalışan tek bir sunucudur (cmd/mcpbase). Projenin OpenAPI ile tanımlanmış HTTP API'sini MCP araçlarına çevirir ve POST /mcp adresinde sunar. İsteğe bağlı runner modu açıldığında, platformda bu elçiliğe atanmış agent'ları yine müşterinin ağında çalıştırır: model olarak yerel bir model (Ollama gibi OpenAI uyumlu bir uç nokta) veya yapılandırılmışsa bir bulut sağlayıcı kullanılır. Her koşunun raporu elçilikte operatör onayını bekler; varsayılan yapılandırmada operatör onaylamadan hiçbir rapor platforma iletilmez.

Akış

sequenceDiagram
    autonumber
    participant P as Agent Tale platformu
    participant E as Embassy (müşteri ağı)
    participant A as Proje API
    participant O as Operatör (TUI)
    P->>P: MCP Base kaydı (Settings, MCP Bases)
    P->>E: Check (MCP initialize + tools/list)
    P->>P: Agent ata (prompt kopyası, cron, max turns)
    E->>P: Sync, GET /api/v1/embassy/sync (API anahtarı)
    P-->>E: Assignment listesi (prompt kopyalarıyla)
    E->>A: Model ile tool-use koşusu (araç çağrıları)
    E->>E: Rapor kaydedilir (pending_approval)
    O->>E: approve_report (POST /admin/mcp)
    E->>P: POST /api/v1/embassy/reports (yalnız onaylı)
    P-->>E: Kabul (aynı rapor tekrar gelirse dedupe)

Kurulum

Elçilik veritabanı kullanmayan tek bir statik binary'dir (services/mcpbase-service/cmd/mcpbase; Docker imajı services/mcpbase-service/Dockerfile). Runner durumu düz JSON dosyalarında tutulur (STATE_DIR altında assignments.json ve reports/<uid>.json); operatör tüm durumu okuyup yedekleyebilir. GET /health proje adını ve araç sayısını döner.

Temel

tools/list spec'teki işlemlerden üretilir, tools/call upstream API'ye iletilir (yanıt en çok 256 KiB).

Keşif (isteğe bağlı)

PATHFINDER_DOCKER · PATHFINDER_DOCKER_HOST · PATHFINDER_DOCKER_HOST_GATEWAY · PATHFINDER_SCAN_CIDRS (yalnız kendi ağınız) · PATHFINDER_SCAN_PORTS · PATHFINDER_PROJECT_DIR · PATHFINDER_ALLOW_CIDRS · PATHFINDER_CONCURRENCY (varsayılan 32). Eski DISCOVER_* adları hâlâ okunur (önce PATHFINDER_* denenir). Biri açıksa pathfinder_discover aracı görünür (eski adı discover_services): Docker konteynerlerini, proje dizinindeki spec dosyalarını ve izin verilen ağ aralıklarını tarar. Platformdaki POST /api/v1/mcp-bases/:id/discover yalnızca aday listesi döner; hiçbir şeyi kendiliğinden kaydetmez.

Runner (isteğe bağlı)

Runner yalnızca üç PLATFORM_* değişkeninin hepsi doluysa başlar; aksi halde elçilik platforma hiç bağlantı açmaz ve yalnızca /mcp ile /health sunar.

PLATFORM_API_KEY, MCP Base kaydının sahibi olan cüzdanla oluşturulmalıdır. Bu iki scope web'deki New key diyaloğunda listelenmez; anahtar oturum açıkken POST /api/v1/user/api-keys ile {"name": "...", "scopes": ["read:assignments", "submit:report"]} gövdesiyle oluşturulur. Platform, bir MCP Base'i rapor gönderen ilk anahtara bağlar; başka bir anahtarla gelen rapor reddedilir.

Platform tarafı

Web: Settings → Developer → MCP Bridge → Go to MCP Bases → (/settings/projects). TUI: MCP Bases sekmesi (n yeni kayıt, s assignment'lar, p raporlar, l yerel onay yüzeyi).

Assignment

• Yalnızca sahibi olduğunuz veya satın aldığınız bir agent atanabilir. Web formu agent kimliği ve isteğe bağlı cron ister.
• Agent'ın prompt'u atama anında kopyalanır (prompt v1). Agent sonradan düzenlenirse elçilikte çalışan metin değişmez; güncel prompt'a geçmek açık bir işlemdir (PUT /api/v1/mcp-bases/:id/assignments/:aid, resync_prompt: true) ve sürüm artar.
• Schedule: 5 alanlı, saniyesiz cron, UTC. Boş bırakılırsa yalnız elle tetiklenir. Geçersiz ifade platformda reddedilir.
• Max turns: varsayılan 5, en çok 20. Web formu varsayılanı kullanır; farklı değer API ile verilir.
• Lore servisi bağlı kurulumlarda platform, senkronda agent'ın Lore bağlamını prompt'un başına ekler. Teslim edilen raporun özeti agent'ın hafızasına, tam metni (araç çağrıları dahil) agent'ın Lore belgelerine yazılır.

Case koşuları

2–5 kayıtlı elçilik seçilir; platform her birini o anda introspect eder ve sonucu LLM ile analiz eder (asenkron, kredi cüzdandan düşülür).

İsteğe bağlı on-chain attestation, başarılı bir Case koşusunun çıktı hash'ini zincire yazar. Yalnızca Case koşuları içindir, koşuyu hiçbir zaman engellemez ve zincir yapılandırılmamış kurulumlarda kullanılamaz.

Onay akışı

stateDiagram-v2
    [*] --> pending_approval: Koşu biter
    pending_approval --> approved: approve_report
    pending_approval --> rejected: reject_report
    approved --> delivering: outbox
    delivering --> delivered: Platform kabul etti
    delivering --> dead: 12 deneme veya 4xx
    dead --> approved: retry_report

• Raporlar elçilikte pending_approval durumunda bekler. pending_approval, rejected ve dead durumları yalnızca elçilikte yaşar; platform yalnızca teslim edilen raporu görür.
• Onay, elçiliğin yerel onay yüzeyinden verilir: POST /admin/mcp, MCP_ADMIN_TOKEN ile. Bu yüzey ayrı bir MCP sunucusudur; araçları platformun introspect ettiği listede ve yerel modelin erişebildiği araçlarda görünmez.
• TUI bu yüzeye --embassy-url http://<elçilik>:8090/admin/mcp --embassy-token <MCP_ADMIN_TOKEN> (veya AGENT_TALE_EMBASSY_URL / AGENT_TALE_EMBASSY_TOKEN, ya da config.toml içindeki [[embassies]] girdileri) ile bağlanır; birden çok elçilik tanımlıysa önce seçim ekranı açılır.

Teslim: onaylı raporlar bir outbox'tan gönderilir. Hata halinde bekleme 30 sn'den 30 dk'ya kadar üstel artar (±%20 sapma); 12 denemeden sonra (yaklaşık 2,5 saat) rapor dead olur. Platformun 4xx ile reddettiği rapor doğrudan dead olur; 409 (rapor platformda zaten var) teslim edilmiş sayılır. Teslim rapor kimliğine göre idempotenttir: yanıtı kaybolan bir tekrar gönderim yeni kayıt açmaz. İlerleme her adımda diske yazılır; çöken elçilik kaldığı yerden devam eder. Platform tarafında rapor başına sınırlar: özet 8 KiB, çıktı 256 KiB, en çok 50 araç çağrısı (64 KiB).

Bugün ne yapar / ne yapmaz

İlgili sayfalar

Toolsets (MCP Bridge) · Connectors · Ayarlar → API Keys · Lore