> For the complete documentation index, see [llms.txt](https://docs.kangal.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kangal.dev/tr/ai-gateway/protocols.md). # Protokoller Kangal, tenant kapsamındaki MCP upstream'lerini ve A2A agent'larını AI Gateway ile aynı kontrol düzlemi üzerinden yayımlar. Protokol trafiğinde doğrulanmış bir Kangal kullanıcı JWT'si kullanılır; header veya JSON içindeki tenant değerleri kimlik olarak kabul edilmez. ## Operatör iş akışı **AI Gateway > MCP / A2A** bölümünü açın, bir gateway seçin ve **MCP upstream** veya **A2A agent** oluşturun. Bu ekranda şunları yapabilirsiniz: * kaynak oluşturma; * kaynağı etkinleştirme veya duraklatma; * kaynak silme; * her 10 saniyede yenilenen son 25 işlemi görüntüleme. Mevcut bir kaynağın URL, token, policy, limit, Agent Card veya etiketlerini değiştirirken `PATCH` kullanın. Yönetici kaynakları şu endpoint'lerde kullanılabilir: ``` POST /admin/gateways/{gateway_id}/protocol-gateway/resources GET /admin/gateways/{gateway_id}/protocol-gateway/resources GET /admin/gateways/{gateway_id}/protocol-gateway/resources/{resource_id} PATCH /admin/gateways/{gateway_id}/protocol-gateway/resources/{resource_id} DELETE /admin/gateways/{gateway_id}/protocol-gateway/resources/{resource_id} GET /admin/gateways/{gateway_id}/protocol-gateway/operations ``` Sürümlü `/api/v1/admin/...` alias'ları da kullanılabilir. Yönetici okuma işlemlerine salt okunur yönetici rolleri erişebilir; yazma işlemleri `admin` veya `super_admin` rolü gerektirir ve gateway tenant'ı ile sınırlandırılır. ## Kaynak alanları ve limitler | Alan | Varsayılan değer ve doğrulama | | --------------------------- | ------------------------------------------------------------------------------ | | `kind` | Zorunlu: `mcp_upstream` veya `a2a_agent` | | `name` | 1-120 karakter; tenant/gateway/ad kapsamında benzersiz | | `description` | En fazla 1.000 karakter | | `enabled` | `true`; devre dışı kaynaklar çalışma zamanında `404` döndürür | | `upstream_url` | 8-2.048 karakter; herkese açık HTTPS, yönlendirme veya özel hedef içermez | | `upstream_bearer_token` | İsteğe bağlı, en fazla 8.192 karakter; şifrelenir ve maskelenir | | `required_scopes` | En fazla 50 tam JWT scope değeri; yapılandırılan scope'ların tümü zorunludur | | `allowed_origins` | En fazla 50 tam tarayıcı origin değeri | | MCP izin listeleri | Liste başına en fazla 500 tool, resource ve prompt | | `max_request_bytes` | Varsayılan 262.144; 1.024-4.194.304 | | `max_response_bytes` | Varsayılan 1.048.576; 1.024-16.777.216 | | `timeout_seconds` | Varsayılan 30; 0,1-300 | | `quota_requests_per_minute` | Varsayılan 120; kimlik/kaynak başına 1-100.000 | | `max_concurrency` | Varsayılan 16; kaynak/process başına 1-1.000 | | `discovery_host` | Yalnızca A2A; şema, path, port veya kullanıcı bilgisi içermeyen DNS hostname'i | | `agent_version` | Varsayılan `1.0.0`, en fazla 80 karakter | | `skills` | Yalnızca A2A, 1-100 yetenek | Her A2A yeteneği `id`, `name` ve `description` alanlarını gerektirir; alan uzunlukları sırasıyla 1-120, 1-120 ve 1-1.000 karakterdir. Bir yetenek en fazla 50 etiket, 20 örnek, 20 giriş modu ve 20 çıkış modu içerebilir. MCP kaynak örneği: ```bash curl -sS -X POST \ "$KANGAL_ADMIN_URL/admin/gateways/$GATEWAY_ID/protocol-gateway/resources" \ -H "Authorization: Bearer $ADMIN_TOKEN" \ -H 'Content-Type: application/json' \ -d "{ \"tenant_id\": \"$TENANT_ID\", \"kind\": \"mcp_upstream\", \"name\": \"support-tools\", \"upstream_url\": \"https://mcp.example.com/mcp\", \"upstream_bearer_token\": \"$UPSTREAM_TOKEN\", \"required_scopes\": [\"mcp:use\"], \"allowed_origins\": [\"https://app.example.com\"], \"tool_allowlist\": [\"tickets.*\", \"knowledge.search\"], \"resource_allowlist\": [\"kb://public/*\"], \"prompt_allowlist\": [\"support-*\"], \"quota_requests_per_minute\": 60, \"max_concurrency\": 8 }" ``` Boş MCP izin listeleri çağrıları ve okumaları reddeder; keşif sonucunu boş liste olarak filtreler. Pattern'ler büyük/küçük harfe duyarlı shell eşleştirmesi kullanır. ## MCP çalışma zamanı | Metot ve path | Kullanım | | --------------------------- | --------------------------------------------------------- | | `POST /mcp/{resource_id}` | Streamable HTTP istekleri, bildirimleri ve yanıt zarfları | | `GET /mcp/{resource_id}` | Mevcut bir oturum için sunucudan istemciye SSE | | `DELETE /mcp/{resource_id}` | Mevcut bir oturumu sonlandırma | Desteklenen protokol sürümleri `2025-11-25`, `2025-06-18` ve `2025-03-26` değerleridir. Yeni istemcileri `2025-11-25` ile başlatın. Desteklenen istek metotları: ``` initialize ping tools/list tools/call resources/list resources/templates/list resources/read prompts/list prompts/get ``` Desteklenen bildirimler `notifications/initialized`, `notifications/cancelled` ve `notifications/progress` değerleridir. MCP `POST` isteği şu header'ları gerektirir: ``` Authorization: Bearer Content-Type: application/json Accept: application/json, text/event-stream ``` Başlatma işleminden sonra dönen `MCP-Session-Id` ve `MCP-Protocol-Version` değerlerini gönderin. Kangal oturum anahtarını yeniden üretir ve oturumu tenant, kaynak, kimlik, protokol sürümü ve upstream oturum kimliğine bağlar. Oturumlar sekiz saat sonra sona erer. Farklı bir kimlik veya scope ile kullanılan oturum `404` döndürür. JSON yanıtları doğrulanmış tek bir JSON-RPC nesnesi olarak iletilir. SSE, header ve content type ön doğrulamasından sonra stream edilir. Kabul edilen bildirimler ve yanıt zarfları gövdesiz `202` döndürür. Sunucu SSE'si artımlı olarak ayrıştırılır; bozuk, limit aşan, yarıda kesilmiş veya geçersiz olaylarda bağlantı güvenli biçimde kapatılır. Kaynak byte limitlerine ek olarak etkin yapı limitleri 20 iç içe seviye, 10.000 JSON değeri, 512 karakterlik nesne anahtarı ve 1.000.000 karakterlik string değeridir. Her zarf içinde tek bir JSON-RPC isteği gönderin; batch istekler reddedilir. ## A2A çalışma zamanı Global olarak benzersiz bir `discovery_host` ve en az bir yetenek ile `a2a_agent` oluşturun. Keşif, host üzerinden yönlendirilir: ``` GET /.well-known/agent-card.json ``` Dönen kart; JSON-RPC binding `1.0`, streaming desteği, Kangal JWT Bearer şeması ve yapılandırılmış yetenekleri duyurur. Kart herkese açık olarak 300 saniye cache'lenir. İşlemleri şu endpoint'e gönderin: ``` POST /a2a/{resource_id} Authorization: Bearer Content-Type: application/json A2A-Version: 1.0 ``` Desteklenen metotlar `SendMessage`, `SendStreamingMessage`, `GetTask` ve `CancelTask` değerleridir. Sürüm header'ı bulunmayan istek eski `0.3` sürümü olarak değerlendirilir ve `VersionNotSupportedError` (`-32009`) döndürür. Streaming yanıtları, SSE `data` alanlarında JSON-RPC yanıt nesneleri olarak iletilir. Keşfedilen task kimlikleri tenant, kaynak, gateway ve oluşturan kimlikle birlikte saklanır. Get/cancel istekleri bu kapsamın tamamıyla eşleşmelidir. Bilinmeyen ve yetkisiz kimlikler aynı şekilde `TaskNotFoundError` (`-32001`) döndürür. ## Güvenlik ve operasyon * Gelen Bearer kimlik bilgileri upstream'e iletilmez; bunun yerine ayrı ve şifrelenmiş upstream token kullanılır. * Tarayıcı isteği `Origin` gönderiyorsa değer `allowed_origins` ile tam olarak eşleşmelidir. Tarayıcı dışı istemciler `Origin` header'ı göndermemelidir. * URL doğrulaması ve sabitlenmiş outbound bağlantı; kimlik bilgisi taşıyan çağrılardan önce yönlendirmeleri, özel/metadata adreslerini ve DNS rebinding'i reddeder. * Dakikalık kota ayırma atomiktir. Kota dolduğunda `Retry-After: 60` ile `429`, eşzamanlılık limiti dolduğunda kuyruğa almak yerine `503` döner. * İşlem kayıtları trace/request/principal/task kimliklerini, metodu, sonucu, durumu, gecikmeyi, byte sayılarını, sınırlandırılmış sayısal kullanımı ve hata türünü içerir. Payload ve kimlik bilgileri saklanmaz. * `GET .../operations`, isteğe bağlı `resource_id` ve 1-200 aralığında `limit` kabul eder; varsayılan limit 50'dir. * `/metrics`; tenant, principal, resource veya trace etiketi olmadan düşük cardinality'li protokol isteği, gecikme, byte ve ret metriklerini yayımlar. Protokol istemcilerinde Kangal kullanıcı JWT profilini ve yukarıda belgelenen sürüm, metot, header ve taşıma davranışlarını kullanın. Production'a geçmeden önce oturum yönetimini, streaming'i, origin politikasını ve upstream timeout'larını hedef ingress ortamında doğrulayın. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.kangal.dev/tr/ai-gateway/protocols.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.