MCP API

MCP API, yapay zeka ajanlarının (Claude, Cursor ve herhangi bir MCP uyumlu client) Alaf Server'ı bir dizi araç olarak kullanmasını sağlayan tek bir Model Context Protocol endpoint'idir. Her araç, izin etiketli bir REST route'a eşlenir ve her çağrı, tam auth ve permission stack'ini yeniden çalıştırır — böylece bir ajan yalnızca token'ının izin verdiği şeyleri görür ve yapar. Client kurulumu (OAuth flow, config snippet'leri) için MCP genel bakışına bakın.

Hem self-hosted hem de Alaf Server Cloud'da (paylaşılan route setinde monte edilmiş olarak) mevcuttur.

Endpoint'ler

Her iki route da public olarak bildirilmiştir (otomatik enjekte edilmiş auth middleware'i yok): POST handler'ı bearer credential'ı kendi başına doğrular ve her tools/call, gerçek permission stack'i üzerinden yeniden kimlik doğrulayan dahili bir request gönderir.

Kimlik doğrulama nasıl çalışır

Eksik veya geçersiz bir bearer, /.well-known/oauth-protected-resource adresini gösteren bir WWW-Authenticate header'ı ile 401 döndürür, böylece OAuth-2.1 MCP client'ları authorization server'ı keşfedebilir ve PKCE flow'unu başlatabilir. Geçerli bir credential, çağrı yapanın effective capability'sini çözer — bu yalnızca tools/list'i filtrelemek için kullanılır, böylece endpoint, token'ın kullanamayacağı araçları tanıtmaz.

Capability, authorization gate değildir. Her tools/call, dahili bir HTTP request'i oluşturur ve çağrı yapanın bearer'ını ileterek gerçek Hono app üzerinden gönderir, böylece routing, validation, auth ve kaynak başına permission check'i, HTTP üzerinden çalıştıkları gibi tam olarak çalışır. Salt okunur bir token yalnızca okuma araçlarına ulaşabilir; scoped bir token, kendisine verilen project'ler, server'lar ve repository'lerle sınırlı kalır.

Endpoint, IP başına rate-limited'dır (mcp policy'si: dakikada 300 request) çünkü kimliği doğrulanmamış bir probe bile bir credential lookup maliyetine sahiptir.

Request body (JSON-RPC 2.0 envelope)

POST body'si tek bir JSON-RPC 2.0 mesajıdır (batching, 2025-06-18 protocol'ünde kaldırılmıştır — bir array body'si -32600 döndürür).

Method'lar

Mevcut araçları listele

POST /api/mcp

curl -s https://your-host/api/mcp \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Register the same endpoint with an MCP client (Claude Code):
claude mcp add --transport http alaf server https://your-host/api/mcp \
  --header "Authorization: Bearer $ALAFSERVER_TOKEN"

Araç seti, bir mcp bloğu ile opt-in yapan Alaf Server'ın izin etiketli route'larından türetilmiştir; credential/auth yüzeyleri (tokens, auth, mcp'nin kendisi) asla ifşa edilmez.

Bir aracı çağır

params.name, tools/list'ten gelen araç adıdır; params.arguments, herhangi bir path parameter'ı, isteğe bağlı bir query object'i, isteğe bağlı bir body object'i (POST/PUT/PATCH araçları için) ve isteğe bağlı bir organizationId'yi (x-organization-id header'ı olarak gönderilir) taşır.

curl -s https://your-host/api/mcp \
  -H "Authorization: Bearer $ALAFSERVER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_projects","arguments":{}}}'

Sonuç, temel API response'unu text content olarak sarar; gönderilen request başarısız olduğunda isError: true olur.

Görebileceğiniz hatalar