# 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.

- **Modül:** Yapay Zeka Ajanları
- **Yöntem:** POST
- **Endpoint:** `https://ws.evobulut.com/api/mcp`
- **Kimlik doğrulama:** `Authorization: Bearer` başlığında ajan anahtarı (Login ve UID gerekmez)
- **Son güncelleme:** 2026-10-09
- **Doküman:** https://dev.evobulut.com/servis/yapay-zeka-ajanlari/mcp-sunucusu-claude-ve-diger-ajanlar-330

## 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.

| Adres | https://ws.evobulut.com/api/mcp |
| --- | --- |
| Aktarım | Streamable HTTP (durumsuz). İstekler JSON-RPC 2.0, yalnız POST. |
| Kimlik | Ajan anahtarı: Authorization: Bearer evo_ak_… (bkz. Ajan Anahtarı ile Kimlik Doğrulama). |
| Yetki / sınır | Ajan 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ı

| Durum | Anlamı |
| --- | --- |
| HTTP 401 | Anahtar yok, geçersiz, iptal edilmiş ya da süresi dolmuş. |
| HTTP 403 | Kullanı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 503 | Anahtar 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

| Authorization | Bearer evo_ak_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| --- | --- |
| Accept | application/json, text/event-stream |

## İstek gövdesi

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

## Örnek istek (cURL)

```bash
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

```json
{
  "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ç)"
      }
    ]
  }
}
```