bulut API Dokümantasyonu
Postman
Ana Sayfa › Yapay Zeka Ajanları › MCP Sunucusu (Claude ve diğer ajanlar)

MCP Sunucusu (Claude ve diğer ajanlar)

MCP Sunucusu (Claude ve diğer ajanlar), Evobulut ön muhasebe / ERP yazılımının Yapay Zeka Ajanları modülüne ait bir REST API servisidir. POST yöntemiyle https://ws.evobulut.com/api/mcp adresine JSON gönderilerek çağrılır; kimlik doğrulama Authorization: Bearer başlığındaki ajan anahtarı ile yapılır (Login ve UID gerekmez).

POSThttps://ws.evobulut.com/api/mcp
Açıklama

MCP (Model Context Protocol), yapay zeka ajanlarının dış sistemlerdeki araçları standart bir yolla keşfedip çağırmasını sağlayan açık protokoldür. evobulut MCP sunucusu; cari, stok, sipariş, teklif, fatura, aktivite ve görev işlemleri için 25 hazır araç sunar (bkz. MCP Araç Listesi). Ajan araçları kendisi listeler; parametreleri ve açıklamaları sunucudan gelir.

Adreshttps://ws.evobulut.com/api/mcp
AktarımStreamable HTTP (durumsuz). İstekler JSON-RPC 2.0, yalnız POST.
KimlikAjan anahtarı: Authorization: Bearer evo_ak_… (bkz. Ajan Anahtarı ile Kimlik Doğrulama).
Yetki / sınırAjan anahtarındaki kurallar aynen geçerlidir. Araçlar evobulut servislerini çağırır; her servis çağrısı istek sınırına sayılır ve kaydedilir. Araç çağrıları çoğunlukla 1 istek tutar; cari_ekle ve siparis_olustur 2, teklif_olustur 3 istek tutar.

Claude Code ile bağlanma

claude mcp add --transport http evobulut https://ws.evobulut.com/api/mcp --header "Authorization: Bearer evo_ak_..."

ya da proje klasöründeki .mcp.json dosyasına:

{
  "mcpServers": {
    "evobulut": {
      "type": "http",
      "url": "https://ws.evobulut.com/api/mcp",
      "headers": { "Authorization": "Bearer evo_ak_..." }
    }
  }
}

Diğer ajanlar

Uzak (HTTP) MCP sunucusu ekleyebilen ve özel başlık gönderebilen her istemci aynı adres ve Authorization başlığıyla bağlanır. OAuth ile bağlanan istemciler için destek ileride eklenecektir.

Güvenlik ilkeleri

  • Yazma araçları taslak üretir: sipariş ve teklif onaysız açılır, onayı kullanıcı evobulut'ta verir.
  • Silme, onaylama, e-belge gönderme ve para hareketi (tahsilat, kasa, banka) araçları yoktur.
  • Yazma araçlarında tekrar_anahtari gönderilirse aynı istek 24 saat içinde ikinci kez kayıt açmaz; ajan zaman aşımında güvenle yeniden deneyebilir. Gönderilmezse aynı içerik 10 dakika içinde tekrar yazılmaz.
  • Vergi ya da TC numarasıyla kayıtlı bir cari varsa cari_ekle yeni kart açmaz, mevcut kartı döner.

Hata kodları

DurumAnlamı
HTTP 401Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş.
HTTP 403Kullanıcı ya da firma pasif, kullanıcı artık API kullanıcısı değil ya da kullanıcı çalışma saatleri dışında.
HTTP 503Anahtar o an doğrulanamadı; kısa süre sonra tekrar deneyin.
Araç hatasıAraç çalıştı ama işlem yapılamadı (eksik/yanlış parametre, yetki, iş kuralı): MCP cevabında isError: true ve açıklayıcı mesaj döner; ajan mesajı okuyup düzeltebilir.
İstek sınırıDakikalık sınır aşılırsa HTTP 429 dönmez; araç isError: true ve "Dakikalık istek sınırı (…) aşıldı" mesajıyla döner. Ajan bir sonraki dakikanın başına kadar bekleyip yeniden denemelidir (yazma araçlarında aynı tekrar_anahtari ile).
Header Bilgileri
AuthorizationBearer evo_ak_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Acceptapplication/json, text/event-stream
İstek Gövdesi (JSON)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
Kod Örnekleri
curl -X POST "https://ws.evobulut.com/api/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer evo_ak_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}'
Başarılı Yanıt
200 OK
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "cari_ara",
        "title": "Cari ara",
        "description": "Müşteri / tedarikçi / kişi kartı (cari) arar. Ad, ünvan ve kodda parça eşleşme; vergi no, TC kimlik no ve telefonda tam eşleşme. …",
        "inputSchema": {
          "type": "object",
          "properties": {
            "ara": {
              "type": "string",
              "description": "Aranacak metin; boşsa en son eklenenler listelenir",
              "default": ""
            },
            "sayfa": {
              "type": "integer",
              "description": "Sayfa numarası, 0'dan başlar",
              "default": 0
            }
          }
        },
        "annotations": {
          "title": "Cari ara",
          "readOnlyHint": true,
          "openWorldHint": false
        }
      },
      {
        "name": "…",
        "description": "(toplam 25 araç)"
      }
    ]
  }
}