# Yapay Zeka Asistanlarını Bağlayın (MCP)

<span data-t="appName">Your AI Connector</span>, AI asistanlarının **Claude Code**, **Claude Desktop**, **Cursor** ve kendi uygulamalarınızın <span data-t="appName">Your AI Connector</span> hesabınızı doğrudan yönetmesini sağlayan bir Model Context Protocol uç noktası olan resmi bir **MCP sunucusu** sunar. Sade bir dille sorun ("AI temsilcilerimi listele", "bu potansiyel müşteriyi ekle", "AI bu hafta bana ne kadara mal oldu?") ve asistan sizin yerinize <span data-t="appName">Your AI Connector</span> API'sini çağırsın.

Kendi API anahtarınızla kimlik doğrulaması yaptığınız, bir [API anahtarı](api-access.md) ile eriştiğiniz v1 API'sinin aynısıdır. MCP sunucusu, yayınlanmış API spesifikasyonumuzdaki her işlem için bir araç oluşturur; bu nedenle v1 API'sinin tamamını olmasa da büyük bir kısmını kapsar: kişiler, mesajlar, kampanyalar, yapay zeka temsilcileri, özel işlevler, bilgi tabanı, randevular, analizler, etiketler, listeler, yayınlar, anlaşmalar, kanal bağlantıları ve alt hesaplar. Otomasyonlar listelenebilir ve okunabilir, ancak henüz MCP aracılığıyla oluşturulamaz veya düzenlenemez; bunları uygulama içinde oluşturun.
Sunduğu özellikler dahilinde araç bazlı izinler veya varsayılan salt okunur erişim bulunmamaktadır, bu nedenle API anahtarı tüm erişim kontrolünü sağlar.

- **Uç Nokta:** `https://mcp.youraiconnector.com/mcp`
- **Kimlik Doğrulama:** <span data-t="appName">Your AI Connector</span> API anahtarınız (`X-API-Key` başlığı olarak gönderilir)
- **Gereksinim:** API erişimi olan bir plan. [Bir API anahtarı oluşturun →](api-access.md#generating-your-api-key)


> API anahtarınız, API'nin geri kalanıyla aynı izinlere sahip olarak **kendi hesabınız** üzerinde işlem yapar ve eğer bir ajans planındaysanız (aşağıya bakın) yönettiğiniz müşteri hesaplarını okuyabilir. Onu bir parola gibi saklayın. Ayarlar → Entegrasyonlar → API Anahtarı kısmından istediğiniz zaman iptal edebilirsiniz; bu, asistanın erişimini anında keser.

## Claude Code



```bash
claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"
```

Ardından, **ai-connector ✓ connected** ifadesinin göründüğünü doğrulamak için Claude Code içinde `/mcp` komutunu çalıştırın.

Varsayılan olarak sunucu **yerel** kapsamda (sadece siz, bu proje) eklenir. Bunu tüm projelerinizde kullanılabilir hale getirmek için `--scope user` kullanın veya ekibiniz için `--scope project` to commit it to a repo's `.mcp.json` ifadesini kullanın:

```json
{
  "mcpServers": {
    "ai-connector": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}
```

## Claude Desktop

Sunucuyu özel bir bağlayıcı olarak ekleyin. Claude hesabınızda ayarlandığı için hem Claude Desktop'ta hem de claude.ai üzerinde aynı şekilde çalışır (ücretsiz Claude hesapları bir adet özel bağlayıcı ekleyebilir).

1. **Özelleştir → Bağlayıcılar** (Customize → Connectors) kısmını açın, **+ Ekle** (+ Add) ve ardından **Özel bağlayıcı ekle** (Add custom connector) seçeneğine tıklayın.
2. Bir isim verin ve URL olarak `https://mcp.youraiconnector.com/mcp` girin.
3. **Kimlik doğrulama** (Authentication) altında **Oturum açma yok** (No sign in) seçeneğini seçin. MCP sunucusunun oturum açma sayfası yoktur: bir oturum açma seçeneği belirlemek "… oturum açma hizmetine kaydedilemedi" hatasıyla sonuçlanır.
4. **İstek başlıkları** (Request headers) altında, `X-API-Key` adında bir başlık ekleyin ve değer olarak API anahtarınızı girin.
5. **Ekle** (Add) düğmesine tıklayın. Yeni bir sohbetin araçlar menüsünde <span data-t="appName">Your AI Connector</span> araçları görünecektir.

**İstek başlıkları alanı yok mu?** Claude Desktop sürümünüz eski: güncelleyin veya bunun yerine yapılandırma dosyasını kullanın. Yapılandırma dosyası (`claude_desktop_config.json`, Ayarlar → Geliştirici → Yapılandırmayı Düzenle) yalnızca bilgisayarınızdaki programları çalıştırır ve `url` girişini yok sayar, bu nedenle [Node.js](https://nodejs.org) 18 veya daha yenisini gerektiren küçük `mcp-remote` köprüsüne ihtiyaç duyar:

```json
{
  "mcpServers": {
    "ai-connector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.youraiconnector.com/mcp",
        "--header",
        "X-API-Key:${AI_CONNECTOR_KEY}"
      ],
      "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" }
    }
  }
}
```

`X-API-Key:${AI_CONNECTOR_KEY}` ifadesini, iki noktadan sonra boşluk bırakmadan (Windows'ta boşluk başlığı böler) tam olarak yazıldığı gibi tutun ve anahtarınızı yalnızca `env` içine yerleştirin. Ardından Claude Desktop'ı tamamen kapatın (Windows'ta tepsi simgesine sağ tıklayın → Çıkış) ve tekrar açın.

## ChatGPT

ChatGPT şu anda MCP sunucusuna bağlanamıyor. Özel bağlayıcı formu yalnızca **OAuth** veya **Kimlik doğrulaması yok** seçeneklerini sunuyor; oysa <span data-t="appName">Your AI Connector</span> MCP sunucusu, istek başlığı olarak gönderilen API anahtarınızla oturum açıyor. OAuth seçildiğinde "OAuth ayarları keşfedilemedi" hatası alınıyor, Kimlik doğrulaması yok seçildiğinde ise her istek anahtar gerektirdiği için reddediliyor.

Bunun yerine istek başlığı ayarlamanıza izin veren bir asistan kullanın:
[Claude Code](#claude-code), [Claude Desktop](#claude-desktop),
[Cursor veya başka bir MCP istemcisi](#cursor--other-mcp-clients) ya da
[Claude API](#the-claude-api-build-it-into-your-own-app).

ChatGPT, bağlantı olmadan da yardım belgelerini okuyabilir: herkese açık
`llms.txt` dosyaları için [Yardım belgeleri yerleşiktir](#the-help-docs-are-built-in) bölümüne bakın.

## Cursor ve diğer MCP istemcileri

MCP destekli çoğu düzenleyici, yukarıda gösterilen `.mcp.json` yapısını (bir `url` ve `X-API-Key` başlığına sahip bir HTTP sunucusu) kullanır. `https://mcp.youraiconnector.com/mcp` adresini işaret eden bir `ai-connector` sunucusu ekleyin ve API anahtarınızı başlık kısmına yapıştırın.

## Claude API (kendi uygulamanıza entegre edin)

MCP sunucusunu Claude API'sinin MCP bağlayıcısı ile programatik olarak bağlayabilirsiniz, böylece oluşturduğunuz bir aracı ayrı bir istemci olmadan <span data-t="appName">Your AI Connector</span> araçlarını kullanabilir:

```json
{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my AI agents" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "ai-connector",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}
```

## Neler yapabilirsiniz

MCP sunucusunun sunduğu v1 API'nin bir parçası dahilinde, asistan doğru aracı otomatik olarak seçer:

- **Yapay zeka temsilcileri:** listeleme, oluşturma, güncelleme, duraklatma/devam ettirme, yapılandırmayı inceleme.
- **Kişiler:** arama, oluşturma, etiketleme, listelere ekleme, içe aktarma.
- **Bilgi tabanı / SSS:** ekleme, düzenleme, toplu içe aktarma, yapay zeka önerilerini onaylama.
- **Mesajlar:** konuşmaları okuma, bir kişiye mesaj gönderme.
- **Randevular:** listeleme, rezervasyon yapma, iptal etme.
- **Görevler:** oluşturma, tamamlama, listeleme.
- **Analitik:** mesaj istatistikleri, kredi kullanımı, yapay zeka maliyeti.
- **Kanallar:** bağlantı durumunu kontrol etme, bağlantı akışını başlatma.

## Müşterilerinizin hesapları hakkında soru sorma (ajanslar)

Tek bir bağlantı, yönettiğiniz tüm hesapları kapsar. Müşteri başına ikinci bir bağlantı eklemenize gerek yoktur: bir ajans planında asistan, altınızdaki herhangi bir müşteri hesabını okuyabilir, böylece hepsine tek bir konuşmada soru sorabilirsiniz.

Sadece müşterinin adını belirtin:

- "Bella's Bistro'nun kaç kişisi var?"
- "Yapay zeka bu hafta müşterilerimin her birine ne kadara mal oldu?"
- "Northside Dental'in kanallarının durumu nedir ve bu hafta kaç sohbet geldi?"

Bu; kişileri, mesajları, sohbetleri, kampanyaları, randevuları, görevleri, etiketleri, etkinlikleri, SSS'leri, bilgi tabanı kaynaklarını, telefon numaralarını, kanalları, web kancalarını ve analizleri okumayı kapsar. Herhangi bir işlem çalışmadan önce hesabın gerçekten size ait olduğunu kontrol ederiz; size ait olmayan bir hesap istendiğinde "bulunamadı" yanıtı döner. Müşteriyi belirtmezseniz asistan, tıpkı daha önce olduğu gibi kendi hesabınızı okur.

**Bir müşterinin hesabını değiştirmek** de aynı şekilde çalışır. API'de bir müşteri hesabını kabul eden her işlem, adlandırılmış bir müşteri için kullanılabilir: yapay zeka temsilcileri, bilgi tabanı, özel işlevler, WhatsApp şablonları, giriş noktaları, kanal bağlantıları, kişiler, etiketler, yayınlar, randevular, anlaşmalar ve görevler oluşturma ve mesaj gönderme. İstisnalar, her zaman kendi ajans hesabınızda çalışan ajans düzeyi işlemlerdir: müşteri hesaplarının kendilerini yönetme (limitler, özellikler, fiyatlandırma, duraklatma), anlık görüntüler, ekibiniz ve API anahtarları. Kişileri bir müşterinin listesine eklemek veya listeden çıkarmak, adlandırılmış bir müşteri için henüz kullanılamamaktadır; bunu o müşterinin kendi anahtarından veya hesabından yapın. [Ajans API kılavuzu](../agency/api-for-agencies.md#where-sub_account_id-is-supported), nelerin desteklendiğini listeler.

::: neutral-mcp
Ajans araçları yalnızca standart, markasız adreste bulunur, `https://mcp.youraiconnector.com/mcp`. Kendi alan adınızdaki (`mcp.youragency.com`) beyaz etiketli (white-label) MCP adresi müşterileriniz için oluşturulmuştur ve bu araçları içermez; bu nedenle müşteri hesaplarını yönetirken standart, markasız adrese bağlanın.
:::

Bu aynı zamanda **tek bir giriş altında birden fazla işletme** yürüten bir müşteri için de cevaptır. Her işletmeye kendi hesabını verin, ardından müşterinin e-postasını hepsine ekip üyesi olarak davet edin: bir kez giriş yaparlar ve kenar çubuğundaki hesap seçici ile markaları arasında geçiş yaparlar.

### Bir müşterinin temsilcisini test etme

Asistan'dan bir müşterinin temsilcisini denemesini isteyin ("X müşterisinin Fırın temsilcisine 'Pazar günleri teslimat yapıyor musunuz?' gönder ve ne yaptığını bana göster"). Bu, ajans anahtarınız ve müşterinin `sub_account_id` bilgisi ile bir Deneme mesajı gönderir, bekler ve yanıtı ile temsilcinin gerçekleştirdiği tüm eylemleri okur. Temsilcinin bir kopyasına gerek yoktur. Asistan bir ajans hesabı olmadığınızı söylerse, bir müşterinin anahtarıyla bağlanmış demektir: onu ajans hesabınızın anahtarıyla yeniden bağlayın. Bkz. [Deneme](../chats/playground.md#testing-an-agent-from-the-api-or-an-ai-assistant).

## Araç sınırı olan istemciler

::: neutral-mcp
Bazı yapay zeka istemcileri yalnızca sınırlı sayıda araca sahip bir sunucuyu kabul eder. Örneğin Composio, 500'den fazla aracı listeleyen bir sunucuyu reddeder ve hiçbirini içe aktarmaz. Tam ajans bağlantısı bundan daha fazlasını listeler, bu nedenle adrese yalnızca ihtiyacınız olan araç gruplarını içeren `?tags=` ekleyin.

Müşteri hesaplarını listelemek, kişilerini, sohbetlerini ve mesajlarını okumak ve mesaj göndermek isteyen bir ajans için:

```
https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages
```

Bu yaklaşık 80 aracı yükler. İsteğinizde müşteriyi belirtin; asistan, yukarıda açıklandığı gibi o müşterinin hesabı üzerinde işlem yapacaktır.

- Grupları virgülle ayırın; büyük veya küçük harf kullanımı fark etmez.
- Tekil araçlar eklemek için, `tools=` ile tam adlarını listeleyin, örneğin `?tags=Contacts&tools=list_or_get_subaccounts`. Her iki listeden de tüm araçları alırsınız.
- Yardım belgeleri araçları her zaman dahildir.
- API anahtarı yine de `X-API-Key` başlığına (veya `Authorization: Bearer YOUR_API_KEY`) yazılmalıdır, asla adrese yazılmamalıdır.
:::

## Yardım belgeleri yerleşiktir

MCP sunucusu, asistana **hesabınızı** ve bu **belgeleri** sağlar. Üç araç yardım belgelerini canlı olarak okur, böylece asistan tahmin yürütmek yerine bir özelliğin nasıl çalıştığını veya yakın zamanda nelerin değiştiğini araştırabilir:

- `docs_search`: bir soruyu yanıtlayan bölümleri bulur ve bunları sayfa bağlantısıyla birlikte döndürür.
- `docs_read`: bir sayfayı bütünüyle veya bir bölümünü okur.
- `docs_list`: her sayfayı alana göre listeler.

Kurulacak hiçbir şey yoktur ve belge araçları hesap verilerinize asla dokunmaz. "Giriş noktaları nasıl çalışır?" veya "otomasyonlarda neler yeni?" diye sorun; asistan önce belgeleri arayacaktır. Araçlar yardım sitesinin kendisini okuduğu için, bir özellik rehberi yayınlandığı anda asistanınız tarafından bilinir.

MCP aracılığıyla bağlı olmayan bir asistan bile belgeleri okuyabilir: onu `https://docs.youraiconnector.com/llms.txt` (her yardım sayfasının Markdown sürümüne bağlantı içeren bir dizini) veya `https://docs.youraiconnector.com/llms-full.txt` (tüm belgelerin tek bir Markdown dosyasındaki hali) adresine yönlendirin. Her ikisi de herkese açıktır, anahtar gerektirmez ve her belge değişikliğinde yeniden oluşturulur.

## API Anahtarınızı Bulma veya Oluşturma

Bu bağlantının kullandığı API anahtarı **Ayarlar → Entegrasyonlar → API Anahtarı** kısmında, Webhook'lardan ayrı olan kendi bölümünde bulunur. Tam adımlar için [API Erişimi](api-access.md#generating-your-api-key) bölümüne bakın.

## Sorun Giderme

- **"Bağlantı reddedildi" veya "bulunamadı"** — adresin sonunda `/mcp` eksik. `https://mcp.youraiconnector.com` yerine `https://mcp.youraiconnector.com/mcp` kullanın.
- **`Needs authentication` / 401** — API anahtarınız eksik veya yanlış. Sunucuyu geçerli bir `X-API-Key` ile yeniden ekleyin.
- **"OAuth ayarları keşfedilemedi" (ChatGPT)** — ChatGPT, özel bağlayıcılar için yalnızca OAuth veya kimlik doğrulaması olmamasını destekler ve MCP sunucusu bir API anahtarı kullandığından, ChatGPT şu an için bağlanamaz. Bkz. [ChatGPT](#chatgpt).
- **"… oturum açma hizmetine kaydedilemedi" veya "bir OAuth İstemci Kimliği ekleyin" (Claude Desktop)** — özel bağlayıcı bir oturum açma seçeneğiyle eklendi. Girilecek bir OAuth istemci kimliği yoktur: bağlayıcıyı kaldırın ve [Claude Desktop](#claude-desktop) bölümünde olduğu gibi **Kimlik Doğrulama → Oturum açma yok** seçeneği ve `X-API-Key` istek başlığı olarak API anahtarınızla tekrar ekleyin.
- **Claude Desktop yapılandırma dosyasını düzenledikten sonra araçları göstermiyor** — yapılandırma dosyası `"url"` girişini yok sayar; özel bağlayıcıyı veya [Claude Desktop](#claude-desktop) içindeki `mcp-remote` formunu kullanın ve uygulamayı tamamen kapatıp yeniden açın.
- **Bir araç `403` döndürüyor** — planınız veya ekip rolünüz bu işleme izin vermiyor; MCP sunucusu fazladan bir kısıtlama uygulamaz, API ile aynı izin denetimidir.
- **Araç bulunamadı** — araç listesi API'den canlı olarak oluşturulur, bu nedenle her zaman mevcut sürümle eşleşir; yenilemek için yeniden bağlanın.
- **Kendi alan adınızda güvenlik veya sertifika uyarısı** — bir DNS kaydını bize yönlendirmek tek başına yeterli değildir: alt alan adının güvenli bir bağlantı sunabilmesi için önce kontrol panelinde doğrulanması gerekir. Beyaz etiket (white-label) ajansları, MCP adresini **Ayarlar → Beyaz Etiketleme** (Settings → White Labeling) altındaki **Özel alan adı** (Custom domain) kartından kendi alan adlarına (örneğin `mcp.youragency.com`) koyabilirler — önce kayıt kuruluşunuzda CNAME'i ekleyin, ardından ana bilgisayar adını **MCP etki alanı (Yapay zeka asistanları)** bloğuna girin ve diğer markalı alt alan adlarınızla aynı akış olan **Doğrula** (Verify) düğmesine tıklayın. Markalı adres ajans araçlarını içermez; bunlar için standart, markasız adresi kullanmaya devam edin. Markalı adresiniz doğrulanana kadar standart, markasız adresi kullanın: müşterilerle paylaşmak güvenlidir.

---

## Sonraki Adımlar

- [API Erişimi](api-access.md) — bu bağlantının kullandığı anahtarı oluşturun veya yenileyin.
- [Webhook'lar](webhooks.md) — bu çekme tabanlı MCP bağlantısının itme tabanlı karşılığı.