Harici araçlar (MCP)

Nereden: Entegrasyonlar → Harici araçlar → MCP sunucusu → Bağla

Kendi sisteminizdeki araçları (sipariş sorgulama, randevu değiştirme, adres güncelleme, iade başlatma…) asistanınıza açarsınız: asistan arayan müşteriniz için bilgi alır ve işlem yapar. Bağlantı MCP (Model Context Protocol) ile kurulur; n8n, Zapier gibi araçlar ya da kendi yazılımınız bir MCP sunucusu yayınlayabilir.

Sunucu IP adresimiz: 2.29.100.197

Başlamadan önce

• İnternetten https:// ile erişilebilen bir MCP sunucusu (Streamable HTTP uç noktası, ör. https://api.firmaniz.com/mcp).
• Gerekiyorsa bir Bearer token ya da özel başlık (ör. X-Api-Key).
• Her araç için açık bir ad, kısa başlık, ne yaptığını anlatan Türkçe açıklama ve parametre şeması (ayrıntı ve örnek JSON yardım merkezindeki Harici araçlar (MCP) makalesinde).

Adım adım

1. Kartta Bağla'ya basın; sunucu adresini ve kimlik doğrulamayı girin.
2. Bağlan ve araçları getir'e basın: e-Temsilci sunucunuzdan araç listesini çeker, uygunluğunu kontrol eder ve gösterir.
3. Asistanın kullanacağı araçları açın. Her araca bir not yazın, gereken doğrulamayı (arayanın numarası, SMS kodu ya da e-posta kodu) ve işlemden önce onay alınıp alınmayacağını seçin.
4. Müşteriyi tanımlayan parametreleri (telefon, e-posta) Arayanın telefon numarası ya da Doğrulanmış e-posta adresi'ne bağlayın: bu değerleri asistan değil e-Temsilci koyar.
5. Kaydet'e basın. Ardından kampanyanın ya da gelen çağrı asistanının Asistan adımında Harici araçları kullanabilsin'i açın.
6. Kampanya sayfasındaki Yazılı dene ile konuşmayı deneyin (yazılı testte araçlar çağrılmaz), sonra bir test aramasıyla gerçek çağrıyı görün.

Sorun yaşarsanız

• Asistan aracı açıklamaya göre seçer: "ne zaman kullanılır" bilgisini açıklamaya ya da nota açıkça yazın.
• Yalnızca bilgi okuyan araçlarda annotations.readOnlyHint: true verin; işlem yapan araçlarda asistan önce müşteriden onay alır.
• Sunucunuz her çağrıda _meta içinde com.etemsilci/call alanını alır: görüşme kimliği ve arayanın doğrulanmış telefonu ya da e-postası. Yetkiyi sunucunuzda da kontrol edin.
• Güvenlik duvarınızda yalnızca 2.29.100.197 IP adresinden gelen isteklere izin verebilirsiniz.
• Araçlarınızı değiştirdiyseniz sayfadaki Araçları yenile'ye basın; ayarlarınız araç adına göre korunur.

Asistan araçları nasıl kullanır?

• Asistan yalnızca açtığınız araçları ve yalnızca kampanyada ya da gelen çağrı asistanında Harici araçları kullanabilsin açıkken kullanır.
• Aracı, açıklamasına ve notunuza bakarak müşterinin isteğiyle ilgili olduğunda seçer; sonucu müşteriye doğal bir cümleyle aktarır.
• İşlem yapan araçlarda (ya da İşlemden önce müşteriden onay alsın açıksa) ne yapacağını söyler ve müşterinin açık onayını alır.
• Bir görüşmede en fazla 10 araç çağrısı yapılır. Sunucunuz cevap vermezse asistan bilgi uydurmaz; ekibinizin döneceğini söyler.
• Her araç çağrısı görüşmenin zaman çizelgesinde Harici araç kullanıldı olarak görünür (araç adı, süre, başarı). Gönderilen değerler kaydedilmez.

Doğrulama

Her araç için müşteriden ne isteneceğini seçersiniz:

Kod 10 dakika geçerlidir; bir görüşmede en fazla 3 kod gönderilir ve 5 kez denenebilir.

Parametre bağlama

Müşteriyi tanımlayan parametreleri asistana bırakmayın: araç ayarlarında Arayanın telefon numarası ya da Doğrulanmış e-posta adresi'ne bağlayın. Bağlı parametreyi asistan görmez; değerini görüşmeden e-Temsilci koyar. Böylece asistan başka bir müşterinin numarasıyla ya da e-postasıyla sorgu yapamaz. E-postaya bağlanan araçlar e-posta kodu doğrulaması ister.

Sunucunuzdan beklenenler

e-Temsilci bir MCP istemcisidir. Sunucunuzun Streamable HTTP uç noktasına tools/list ile araç listesini sorar, görüşmede tools/call ile aracı çağırır. MCP'nin güncel sürümüyle de, initialize el sıkışmalı önceki sürümleriyle (2025-03-26 ve sonrası) de konuşur.

Her araç için:

• name: aracın adı (harf, rakam, _ . -), ör. siparis_durumu.
• title: kısa ad (panelde ve asistanın anlatımında).
• description: aracın ne yaptığı ve ne zaman kullanılacağı, açık ve Türkçe.
• inputSchema: parametreler (JSON Schema): type, description, enum, zorunlular (required). En fazla 20 parametre ve iki seviye iç içe nesne. $ref, anyOf, oneOf, allOf gibi yapılar desteklenmez; böyle bir araç Kullanılamaz olarak görünür.
• annotations.readOnlyHint: yalnızca bilgi okuyan araçlarda true.

Örnek tools/list cevabı:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "siparis_durumu",
        "title": "Sipariş durumu",
        "description": "Müşterinin siparişinin durumunu ve kargo takip numarasını getirir. Sipariş numarası verilmezse müşterinin telefonuyla son siparişi bulur.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "telefon": {"type": "string", "description": "Müşterinin telefonu (+90…)"},
            "siparis_no": {"type": "string", "description": "Sipariş numarası, ör. A1234 (isteğe bağlı)"}
          },
          "required": ["telefon"]
        },
        "annotations": {"readOnlyHint": true}
      },
      {
        "name": "randevu_iptal",
        "title": "Randevu iptali",
        "description": "Müşterinin yaklaşan randevusunu iptal eder. Önce randevu tarihini müşteriye söyleyip onay alın.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "eposta": {"type": "string", "description": "Müşterinin e-postası"},
            "randevu_id": {"type": "string", "description": "İptal edilecek randevu"},
            "neden": {"type": "string", "enum": ["musteri_istegi", "hastalik", "diger"]}
          },
          "required": ["eposta", "randevu_id"]
        },
        "annotations": {"readOnlyHint": false, "destructiveHint": true}
      }
    ]
  }
}

Bu örnekte telefon parametresini Arayanın telefon numarası'na, eposta parametresini Doğrulanmış e-posta adresi'ne bağlarsınız.

Araç çağrılarında params._meta içinde com.etemsilci/call alanı gelir: call_id, direction (gelen/giden) ve caller (phone, phone_verified: caller_id ya da sms, doğrulanmışsa email). Araç cevabının content içindeki metin öğeleri asistana verilir (en fazla 4000 karakter); hata durumunda isError: true dönün ve metinde nedenini yazın.

Sorun yaşarsanız

• Kimlik bilgilerini kabul etmedi: token ya da başlığı kontrol edin; sunucunuz 401/403 dönüyor.
• MCP Streamable HTTP ile cevap vermedi: adresin MCP uç noktası olduğundan emin olun (genellikle /mcp ile biter). Eski HTTP+SSE taşıması (2024-11-05) desteklenmez.
• Kullanılamaz görünen araç: nedeni aracın altında yazar; çoğunlukla parametre şemasındaki desteklenmeyen bir yapıdır.
• Sunucunuz 5 dakika içinde 5 kez hata verirse araçlar 2 dakika kullanılmaz; asistan bu sürede ekibinizin döneceğini söyler.