Agent-First Mimari: API'lerin Geleceği MCP

2025'te herkes "AI API'leri çağıracak" diyordu. 2026'da bu gerçek oldu — ama kimsenin tahmin etmediği bir şekilde.

AI agent'lar API çağırmaya başladı. Ama REST API'leri onlar için tasarlanmamıştı. Swagger dokümanları insanlar içindi. JSON Schema insan gözüyle okunmak içindi. Hata kodları "developer experience" odaklıydı.

Sonra Anthropic MCP'yi duyurdu. Ve her şey değişti.

REST'in kör noktası

REST, 2000'de Roy Fielding'in doktora teziyle doğdu. 25 yıldır web'in omurgası. İnsan developer'lar için mükemmel: predictable URL'ler, HTTP verb'leri, stateless iletişim.

Ama bir AI agent için REST şöyle görünür:

Agent: "Kullanıcının son siparişini getir."
API: 401 Unauthorized
Agent: "Token mı gerekiyor? Nereden alacağım?"
API: [sessizlik]
Agent: "GET /orders?filter=latest döneyim..."
API: 400 Bad Request — "use 'sort' not 'filter'"
Agent: "..."

AI agent'lar REST'in implicit kontratlarını anlamaz. Onlar explicit'e ihtiyaç duyar. Her şeyin yazılı olduğu, keşfedilebilir, makine-okunabilir bir sözleşmeye.

MCP tam olarak bu.

MCP nedir?

Model Context Protocol (MCP), Anthropic tarafından Kasım 2024'te duyurulan, AI agent'ların araçları ve veri kaynaklarını keşfetmesi için standart bir protokol. JSON-RPC 2.0 üzerinde çalışıyor.

Basitçe: AI agent'ınıza "şu tool'ları kullanabilirsin" diyorsunuz. Agent, tool'ların isimlerini, parametrelerini, açıklamalarını JSON-RPC üzerinden keşfediyor. Sonra ihtiyacı olanı çağırıyor.

// Agent sorar:
{"method": "tools/list"}

// Sunucu cevap verir:
{"tools": [{
  "name": "get_weather",
  "description": "Belirtilen şehrin hava durumunu getirir",
  "inputSchema": {
    "type": "object",
    "properties": {
      "city": {"type": "string", "description": "Şehir adı"}
    }
  }
}]}

// Agent çağırır:
{"method": "tools/call", "params": {"name": "get_weather", "arguments": {"city": "İstanbul"}}}

Bu kadar basit. Ama bu basitlik, API tasarımında bir paradigma değişimini temsil ediyor.

Agent-first API tasarımının 5 prensibi

RustAPI'yi geliştirirken, MCP'yi native destekleyen ilk web framework'ü yaparken öğrendiğim prensipler:

1. Her endpoint kendini açıklamalı

İnsan developer için GET /api/v2/orders?sort=desc&limit=10 yeterli olabilir. Ama AI agent için yeterli değil.

Agent-first API'de her endpoint'in bir description'ı, her parametrenin bir açıklaması, her response'ın bir schema'sı olmalı. Swagger/OpenAPI zaten bunu yapıyordu — ama MCP bunu runtime'da, agent tarafından keşfedilebilir hale getiriyor.

2. Input/output kontratı explicit olmalı

AI agent'lar, "şu durumda şu HTTP status döner" gibi implicit bilgileri anlamaz. Onlara her olasılığı söylemelisiniz:

## Bu endpoint ne döndürür?

- 200: Başarılı — WeatherResponse JSON
- 404: Şehir bulunamadı — ErrorResponse JSON  
- 429: Rate limit aşıldı — lütfen 60 saniye bekle
- 500: Sunucu hatası — tekrar dene

Bunu MCP'nin tool description'ına yazdığınızda, agent hata durumlarını yönetebiliyor. REST'te bu bilgiyi nerede veriyordunuz? Belki Swagger'da, belki dokümanda, belki hiçbir yerde.

3. Tool'lar composable olmalı

Bir AI agent nadiren tek bir endpoint çağırır. Genelde birkaç endpoint'i zincirler:

1. Kullanıcıyı bul (search_users)
2. Siparişlerini getir (get_orders)
3. En sonuncusunu bul (— bunu agent kendi yapar)
4. Kargoyu sorgula (track_shipment)

Agent-first API'de tool'lar, birbirinin output'unu input olarak alabilecek şekilde tasarlanmalı. search_users'ın döndüğü user_id, get_orders'ın beklediği user_id ile aynı isimde ve aynı formatta olmalı.

Buna tool compatibility diyorum.

4. Permission modeli granular olmalı

İnsan developer'a "bu API key ile her şeyi yapabilirsin" diyebilirsiniz. AI agent'a diyemezsiniz.

Agent-first API'de permission modeli şöyle olmalı:

• Agent X, read:orders yapabilir ama write:orders yapamaz
• Agent Y, read:orders + read:users yapabilir ama delete:* yapamaz
• Agent Z (admin agent), her şeyi yapabilir ama amount > 10000TL olan işlemlerde insan onayı ister

RustAPI'de bunu MCP Permission Scoping ile yapıyorum (v0.1.508). Her MCP tool'una scope atayabiliyorsunuz, her agent'a scope set'i tanımlayabiliyorsunuz.

5. Output, agent-readable olmalı

Bu kritik. İnsan için yazdığınız response:

{"message": "Siparişiniz başarıyla oluşturuldu, teşekkürler!"}

AI agent için yazdığınız response:

{
  "order_id": "ord_2026_0706_001",
  "status": "confirmed",
  "estimated_delivery": "2026-07-08T14:00:00+03:00",
  "total_amount": {"value": 149.90, "currency": "TRY"},
  "tracking_url": "https://kargo.example.com/track/TRK123456"
}

İnsan "teşekkürler" mesajını okur ve mutlu olur. AI agent order_id'ye bakar ve bir sonraki işleme geçer. İkisi farklı dünyalar.

Gerçek dünyadan bir örnek: SemantiCAD

SemantiCAD'de MCP'yi nasıl kullandığımızı anlatayım. SemantiCAD, bir CAD dosyasını (STEP/DXF) alıp maliyet, BOM (Bill of Materials) ve üretim adımları çıkaran bir sistem. Bunu yapmak için birden fazla AI modelini zincirliyor.

Eski yöntem: Her model için ayrı bir Python script'i yaz, output'u parse et, sonrakine pipe'la. Her şey kırılgan, her şey ad-hoc.

Yeni yöntem (MCP ile):

1. STEP Parser Tool: "Bu STEP dosyasını parse et, geometrik feature'ları çıkar"
2. BOM Generator Tool: "Bu feature listesinden malzeme listesi oluştur"
3. Cost Estimator Tool: "Bu BOM ve feature listesinden maliyet tahmini yap"
4. Process Planner Tool: "Bu feature listesinden üretim adımlarını planla"

Her tool bir MCP endpoint'i. Ana agent (Claude veya DeepSeek), bu tool'ları sırayla çağırıyor. Her tool'un input/output kontratı explicit. Tool'ları istediğiniz sırada zincirleyebilirsiniz. Yeni bir tool eklemek, mevcut hiçbir şeyi bozmaz.

Sonuç: %96 BOM accuracy. Eski yöntemde %70'lerdeydik. MCP'nin getirdiği yapılandırılmış iletişim sayesinde.

MCP vs REST vs gRPC vs GraphQL

Hangisi ne zaman?

Geleceğin stack'i: İnsanlar için REST/GraphQL, servisler için gRPC, AI agent'lar için MCP. Üçü aynı backend'te, aynı endpoint'lerin farklı "görünümleri" olarak.

RustAPI'de tam olarak bunu yapıyorum. Bir endpoint yazıyorsunuz, otomatik olarak REST (HTTP) ve MCP (JSON-RPC) endpoint'i olarak expose ediliyor. Aynı kod, iki protokol.

2026-2027'de ne göreceğiz?

Tahminlerim:

1. Her SaaS'ın bir MCP endpoint'i olacak. Tıpkı 2015'te her SaaS'ın bir REST API'si olması gibi.
2. Agent-first, insan-second. Yeni API'ler önce AI agent'lar için, sonra insan developer'lar için tasarlanacak.
3. MCP Gateway'ler yaygınlaşacak. Tüm şirket API'lerini tek bir MCP endpoint'inde toplayan gateway'ler.
4. Agent-to-agent protokolleri. Sadece agent-to-API değil, agent-to-agent iletişim protokolleri de standartlaşacak.
5. Permission modelleri en büyük problem olacak. Bir AI agent'ın neye erişebileceğini kim, nasıl kontrol edecek?

Sonuncusu özellikle kritik. Security community'nin henüz yeterince konuşmadığı bir konu. Ama yakında patlayacak.

Şimdi ne yapmalısınız?

Eğer bir API geliştiriyorsanız, bugün başlayın:

1. Mevcut API'nize bir MCP endpoint'i ekleyin. 3-5 tool ile başlayın.
2. Her endpoint için explicit description ve input/output schema yazın. Sadece tip değil, gerçekten açıklayıcı metin.
3. Bir AI agent ile test edin. Claude Desktop'a MCP sunucunuzu bağlayın ve "kullanıcının son siparişini getir" deyin. Ne oluyor? Nerede takılıyor?
4. Permission modelini düşünün. Agent'ların neye erişebileceğini, neyi değiştirebileceğini belirleyin.

Gelecek agent-first. Şimdiden hazırlananlar, 2027'de bir adım önde olacak.

Bu yazı RustAPI'nin MCP mimarisinden ve SemantiCAD'deki MCP kullanımından öğrendiklerimle yazıldı. Bir sonraki yazıda Hyperembed ve embedding inference motorunun nasıl çalıştığını anlatacağım.