# Yapay Zekâ İstemcilerini Bağlamak

> Claude Code, Cursor, Claude Desktop ve diğer her MCP istemcisi için yapıştırmaya hazır kurulum; ayrıca token'lar, uzaktan erişim ve bir endpoint'i ajansız doğrulama.

- Güncelleme: 2026-11-04
- Kaynak: https://contextator.com/tr/docs/connecting-ai-clients/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
Her proje tek bir URL'dir. Bir istemciyi ona, projenin token'ıyla birlikte yöneltin; ajan beş dokümantasyon
aracı kazanır — satıcıya ait bir API key ya da plugin gerekmez.

```
http://localhost:3444/mcp/<project-name>
```

Panonun **Connect an agent** paneli, aşağıdaki her parçayı gerçek URL ile doldurulmuş, kopyalamaya
hazır biçimde yazdırır — proje bir token gerektiriyorsa `Authorization` header'ı dahil. Örneklerde
`demo`'yu kendi proje adınızla, `ctxm_9f3a…`'yı proje sayfasının size gösterdiği token ile değiştirin.

---

## Claude Code

Yeni bir proje varsayılan olarak bir token gerektirir, bu yüzden projenizin token'ıyla header'ı ekleyin:

```bash
claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo \
  --header "Authorization: Bearer ctxm_9f3a…"
```

Projenin **MCP access**'i **open**'a çevrildiyse header'ı çıkarabilirsiniz:

```bash
claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo
```

Çalıştığını kontrol edin:

```bash
claude mcp list
```

Sonra yalnızca dokümantasyonunuz hakkında bir soru sorun — Claude Code, `search_docs`'u kendiliğinden
çağırmaya karar verir, çünkü sunucu neyi tuttuğunu anlatır.

## Cursor

Her proje için `~/.cursor/mcp.json`, ya da tek bir depo içinde `.cursor/mcp.json`. Yeni bir proje
varsayılan olarak bir token gerektirir:

```json
{
  "mcpServers": {
    "demo-docs": {
      "url": "http://localhost:3444/mcp/demo",
      "headers": { "Authorization": "Bearer ctxm_9f3a…" }
    }
  }
}
```

Projenin **MCP access**'i **open**'a çevrildiyse `headers` bloğunu çıkarabilirsiniz:

```json
{
  "mcpServers": {
    "demo-docs": { "url": "http://localhost:3444/mcp/demo" }
  }
}
```

Cursor'ı yeniden başlatın, sonra **Settings → MCP**'de yeşil bir gösterge arayın.

## Claude Desktop

Claude Desktop stdio konuşur, bu yüzden bir köprüye ihtiyaç duyar. Yeni bir proje varsayılan olarak bir
token gerektirir ve `mcp-remote` onu `--header` ile iletir; `claude_desktop_config.json` içinde:

```json
{
  "mcpServers": {
    "demo-docs": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "http://localhost:3444/mcp/demo",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer ctxm_9f3a…" }
    }
  }
}
```

Token `env` içinde durur ve header argümanında bilerek boşluk yoktur: Windows'ta Claude Desktop `args`'ı
`npx`'e boşlukları kaçırmadan iletir, bu yüzden `"Authorization: Bearer …"` ikiye bölünmüş hâlde gelir ve
her istek `401` ile döner. Bu düzen token'ı süreç listesinin dışında da tutar.

Projenin **MCP access**'i **open**'a çevrildiyse `--header` argümanını çıkarabilirsiniz:

```json
{
  "mcpServers": {
    "demo-docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:3444/mcp/demo"]
    }
  }
}
```

Claude Desktop'ı yeniden başlatın. Araçlar connectors simgesinin altında görünür.

Yapılandırma dosyası konumları: macOS `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows `%APPDATA%\Claude\claude_desktop_config.json`.

## Başka herhangi bir MCP istemcisi

Ona URL'yi verin — token gerektiren bir proje için token'ı da. Bağlanmanın yolu **Streamable HTTP**'dir;
eski transport eski istemciler için aynı adreste hâlâ sunulur ve sunucu, istemcinin gönderdiğine göre
seçer:

- **Streamable HTTP** (güncel istemciler, bunu kullanın): bir `initialize` isteğini `POST` edin; session id
  `mcp-session-id` header'ında geri gelir.
- **HTTP + SSE** (protokol `2024-11-05`, eski): URL'yi `GET` edin; sunucu
  `/mcp/demo/messages?sessionId=…`'i işaret eden bir `endpoint` olayıyla yanıt verir. Kullanımdan
  kaldırılmıştır — çalışmaya devam eder, her yanıt `Deprecation: @1790899200`, `Sunset: Sat, 02 Oct 2027 00:00:00 GMT` ve
  [uyumluluk politikasını](https://github.com/Contextator/Contextator/blob/main/docs/compatibility.md#legacy-httpsse) gösteren bir `Link` header'ı taşır ve yeni istemciler
  onun üzerine kurulmamalıdır. 2027-10-02'den sonraki ilk `1.x` minor sürümünde kaldırılabilir (daha erken yalnızca,
  düzeltilemeyen bir güvenlik açığı için).

İkisi arasında geçiş yapan bir yapılandırma yoktur.

## Token gerektiren projeler

**MCP access**'i **token required** olan bir proje, geçerli bir token olmadan gelen her isteği,
istemcinin hangi transport'u kullandığından bağımsız olarak `401` ve bir
`www-authenticate: Bearer realm="<project-name>", resource_metadata="<base-url>/.well-known/oauth-protected-resource/mcp/<project-name>"` header'ıyla (`resource_metadata` işaretçisi, bir OAuth istemcisinin keşfe başladığı yerdir) yanıtlar. Token'ı proje sayfasında
üretin — yalnızca bir kere gösterilir — ve sıradan bir header olarak gönderin:

```
Authorization: Bearer ctxm_9f3a…
```

- Header **her** `/mcp/*` isteğinde kontrol edilir. Eski SSE transport'unda bu, stream'i açan `GET`
  isteği *ve* `/mcp/demo/messages`'a giden `POST`'lar anlamına gelir; bu yüzden yalnızca ikisinden
  birine header ekleyebilen bir istemci bağlanamaz. Bir tarayıcı `EventSource`'u genelde bu durumdur —
  o projeleri açık bırakın ya da tüm örneği kimlik doğrulayan bir proxy'nin arkasına koyun.
- Token'lar proje başınadır. İki token korumalı projeye bağlı bir istemcinin her biri için birer
  token'a ihtiyacı vardır.
- Bir token'ı iptal etmek, istemcisini oturum ortasında hemen keser; bir projeyi **open**'dan
  **token required**'a çevirmek de öyle. Güncel bir token ile yeniden bağlanmak tek gereken şeydir.

Bu anahtarın nerede olduğu ve kimin çevirebileceği: [Projeler](/tr/docs/projects/).

## Bir token'ı bazı kaynaklarla sınırlamak

0.6.0'dan beri statik bir `ctxm_…` token'ı projenin bazı kaynaklarına bağlanabilir; böylece tek bir kaynağa ihtiyacı olan bir CI
işi ya da ajan hepsini teslim almaz. Token'ı üretirken **Only these sources**'ı seçin ya da `POST /api/projects/:id/mcp-tokens`'a
`sources` (kaynak **adları**) gönderin; sonradan `PATCH /api/projects/:id/mcp-tokens/:tokenId/sources` ile değiştirin. Token'ın bir
sonraki isteğinde etkili olur ve üretmek ya da değiştirmek bir `editor`'ün işidir.

Kapsam dışındaki bir kaynak **token için yoktur**: ondan hiçbir şey `search_docs`, `read_document`, `list_topics`, `whats_new`
(eklenen, değişen ve kaldırılan satırlar dahil), `resources/list` ya da `resources/read` içinde görünmez. Filtre SQL'de,
sıralamadan, sayfalamadan ve saymadan önce uygulanır ve kapsam dışındaki bir kaynak adı bilinmeyen bir kaynak olarak yanıtlanır.

- Yalnızca statik bir token kapsam taşır. Bir OAuth kimlik bilgisi hesabın üyeliğidir ve **account required** modundaki bir proje
  statik token'ları reddeder.
- Tüm kaynakları silinmiş bir kapsam hiçbir şey okumaz, asla projenin tamamını değil; token listesi onu **Scope empty** ile işaretler.
- **Open** bir projede kapsam bir sınır değildir: hiç token taşımayan bir istek projenin tamamını okur.
- OAuth kimlik bilgileri, API token'ları ve `/api/*` etkilenmez.
- **0.6.0'dan önceki bir sürüme dönmek, kapsamlı her token'ı projenin tamamına genişletir**, çünkü eski kod kapsamı okumaz. Sürüm
  düşürmeden önce kapsamlı token'ları iptal edin.

## Hesap zorunlu kılan projeler

**account required** üçüncü moddur ve bu panonun üyeliklerinin `/mcp/*`'a ulaştığı moddur. Statik bir
`ctxm_…` token kimseyi adlandırmaz ve orada reddedilir; bir istemcinin projenin **üyesi** olan bir hesap
adına davranması gerekir ve bu **her** istekte yeniden denetlenir — bir üyeliği kaldırmak, bir hesabı
devre dışı bırakmak ya da parolasını sıfırlamak bağlantıyı bir süre dolumunda değil, bir sonraki
çağrısında keser.

İstemci bu kimlik bilgisini **OAuth 2.1** üzerinden alır; tarayıcı tabanlı MCP connector'larının zaten
konuştuğu şey budur. Hiçbir şey yapılandırmazsınız: connector'ı
`http://host:3444/mcp/<project-name>`'e yöneltin; sunucunun yetkilendirme endpoint'lerini keşfeder,
kendini kaydeder ve sizi buradaki bir sayfaya, oturum açıp onaylamanız için gönderir. Geri aldığı şey
*sizin* hesabınız olarak davranır, sessizce kendini yeniler ve connector bir ay kullanılmazsa süresi
dolar. Parolanızı değiştirmek, sizin adınıza davranan her connector'ın bağlantısını keser.

Bir connector kendini iki yoldan biriyle tanıtabilir: `/oauth/register` üzerinden kayıt olur ya da `client_id` olarak
yolu olan bir `https://` URL'si — bir **Client ID Metadata Document (CIMD)** — gönderir ve kayıt çağrısını atlar.
Yetkilendirme sunucusu ikincisini `client_id_metadata_document_supported: true` ile duyurur. Sunucu belgeyi
Confluence'ın kullandığı aynı egress guard'ı üzerinden alır (yalnızca https; loopback, link-local, özel ya da
belirtilmemiş adres asla, DNS'ten sonra ve her yönlendirmede denetlenir), en çok 5 KiB okur, en çok 5 saniye bekler
ve `Cache-Control` ya da `Expires` başlığının izin verdiği kadar saklar — başlık yoksa 5 dakika, en çok bir gün.
Belgenin `client_id`'si URL'ye eşit olmalı, `client_name` ve `redirect_uris` zorunlu, secret reddedilir ve
istemcinin istediği `redirect_uri` belgede tam olarak listelenmiş olmalıdır. Onay sayfası belgeyi yayımlayan
host'u ve yanıtın nereye gittiğini yazar, istemci yalnızca localhost'a yönlenebiliyorsa uyarır.
`/oauth/register` üzerinden kayıt eskisi gibi çalışır.

Onay, yalnızca projeyi okuyabilen kişiler içindir. Oturum açmış ama üye olmayan biri, onay sayfası yerine
"No access to this project" sayfasını görür ve connector'a hiçbir şey yönlendirilmez. Onay yine de
gönderilirse connector `access_denied` ile geri gönderilir. Onaylanmış, sonra projesini kaybeden — proje
silindiği için ya da hesap artık onu okuyamadığı için — bir connector, code exchange'de `400 invalid_grant`
ile reddedilir.

`MCP_OAUTH=0` akışın tamamını kaldırır; o zaman kapalı bir projeyi yalnızca statik tokenlar açar — bu da
tarayıcı tabanlı connector'ların hiç bağlanamaması demektir.

## Araçlar için bir Agent Skill

Depo, Agent Skills biçimini okuyan asistanlar için bir Agent Skill, `skills/contextator/SKILL.md`, taşır. Asistana bir Contextator
MCP endpoint'inde `search_docs`, `list_topics`, `read_document`, `whats_new` ve `report_gap`'i hangi sırayla kullanacağını,
dayandığı her pasajın dosya yolunu alıntılamasını ve doküman bir soruyu karşılamıyorsa bunu söylemesini anlatır. Hiçbir araç
eklemez ve sunucunun davranışını değiştirmez; endpoint onunla da onsuz da aynı çalışır.

## Protokol dönemleri

`/mcp/<project-name>` tek bir URL'de MCP'nin iki sürümünü sunar. Aralarında seçim yapmak için hiçbir şey
yapılandırmazsınız.

- **2025-11-25** oturum protokolüdür: `initialize`, ardından sunucunun tuttuğu bir `Mcp-Session-Id`. 0.3.0'dan
  önce var olan her istemci onu konuşur ve hepsi çalışmaya devam eder; bölümün sonundaki üç değişiklik hariç. Endpoint üzerindeki GET, HEAD ve
  DELETE ile eski HTTP+SSE taşıması yalnızca 2025-11-25'tir.
- **2026-07-28** durumsuzdur: `initialize` yok, oturum yok ve her istek protokol sürümünü ve istemci yeteneklerini bir
  `_meta` zarfında kendisi taşır. İstemci önce sunucunun hangi protokol sürümlerini ve yeteneklerini sunduğunu
  öğrenmek için `server/discover` çağırabilir, sonra doğrudan `tools/call` yapar. İstek, protokol sürümünü
  `MCP-Protocol-Version` başlığında, metodu `Mcp-Method` başlığında ve `tools/call`, `resources/read` ile
  `prompts/get` için araç adını, kaynak URI'sini ya da prompt adını `Mcp-Name` başlığında yinelemelidir
  (ASCII olmayan bir değer `=?base64?…?=` olarak gönderilir).

2026 zarfını taşımayan bir istek, `initialize` dahil, 2025-11-25 sayılır. Başlığı eksik ya da çelişen bir 2026
isteği `400` ve JSON-RPC kodu `-32020` ile, desteklenmeyen bir protokol sürümü `400` ve `-32022` ile, zarfı eksik
olan bir istek `400` ve `-32602` ile, bilinmeyen bir metot ise `404` ve `-32601` ile reddedilir. Var olmayan bir proje için
gelen 2026 isteği `404` / `-32602` ile yanıtlanır.

İki dönem neye ulaştıklarında değil, ne döndürdüklerinde ayrışır: ikisi de aynı kimlik doğrulaması altında aynı
araçları, kaynakları ve prompt'ları görür. 2026-07-28 istemcisi her aracın `outputSchema` ve `structuredContent`
alanlarını her zaman alır (bkz. [MCP Araçları](/tr/docs/mcp-tools/#yapılandırılmış-çıktı)); `tools/list`,
`resources/list` ve `resources/read` yanıtları bir önbellek ipucu taşır: `ttlMs`, projenin son başarılı
indekslemesinden bu yana geçen sürenin onda biri, en çok bir saat, indeksleme sürerken, ilk indekslemeden önce ya da başarısız bir indeksleme çalışmasından sonra
`0`; ve `cacheScope`, yalnızca erişimi **open** olan bir projede `public`, aksi halde `private`. Bir kaynağı silmek
ya da projenin erişim modunu değiştirmek ipucunu sıfırlamaz; bu yüzden bir istemci önceki yanıtı bir saate kadar
görebilir. 2025-11-25 yanıtı bunların hiçbirini taşımaz. `contextator_mcp_requests_total{method,tool,era}`
metriği, istemcilerinizin hangi dönemi kullandığını gösterir.

MCP SDK'sının 2. sürümüne geçişle üç şey 2025-11-25 istemcileri için de değişti ve eski davranışa dayanan bir istemcinin
güncellenmesi gerekir: var olmayan bir kaynak artık `-32002` yerine `-32602` döner; bir aracın girdi şeması draft-07
yerine JSON Schema draft 2020-12'dir ve artık `execution.taskSupport` taşımaz; doğrulama hatası `Input validation error: Invalid arguments for tool search_docs: query: …` biçiminde yazılır.

## Aynı anda birden fazla proje

Proje başına bir girdi ekleyin. İzole kalırlar — ikisine de bağlı bir ajanın basitçe iki ayrı araç
seti olur ve birindeki bir arama diğerinden hiçbir zaman belge döndürmez.

```json
{
  "mcpServers": {
    "billing-docs": { "url": "http://localhost:3444/mcp/billing" },
    "mobile-docs":  { "url": "http://localhost:3444/mcp/mobile" }
  }
}
```

---

## Başka bir makineden bağlanmak

1. Sunucunun erişilebilir olduğundan emin olun: `HOST=0.0.0.0` (varsayılan) ve port açık.
2. `localhost` değil, sunucunun adresini kullanın: `http://docs.internal:3444/mcp/demo`.
3. Bir reverse proxy arkasında, panonun doğru URL'leri yazdırması için `PUBLIC_BASE_URL`'i ayarlayın
   ve response buffering'i kapatın — bkz. [Kurulum](/tr/docs/installation/).

:::note
**Bir proje açık bırakılabilir.** **MCP access**'i **open** iken, porta ulaşan herkes onda indekslenmiş
her belgeyi anonim olarak okuyabilir — yeni bir proje varsayılan olarak böyle değildir, ama kendi
sayfasından bu şekilde çevrilebilir. Proje sayfasında bir token ya da hesap zorunlu kılın, portu özel
bir ağda tutun ya da önüne bir kimlik doğrulama koyun — bkz. [Güvenlik](/tr/docs/security/). Bir token
kendi başına bir kapıdır ve kimseyi adlandırmaz; bir hesabı adlandıran kimlik bilgisi ise **open** dâhil
her modda o hesabın üyeliğine karşı denetlenir.
:::

## Bir ajan olmadan doğrulamak

Depoyla birlikte bir smoke test gelir. Bir kaynak checkout'undan:

```bash
npm install
npm run smoke -- http://localhost:3444/mcp/demo "how do I re-index"
npm run smoke -- http://localhost:3444/mcp/demo "kurulum" --sse   # eski transport'u da dener
```

Gerçek bir MCP handshake yapar, araçları listeler ve bir arama çalıştırır. Bir `Authorization`
header'ı gönderemez, bu yüzden bir token gerektiren proje ona `401` yanıtı verir — o durumu bunun
yerine `curl` ile kontrol edin:

```bash
curl -s -i -X POST http://localhost:3444/mcp/demo \
  -H "Authorization: Bearer ctxm_9f3a…" \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
```

## Bağlanmıyorsa

| Belirti | Kontrol edin |
|---------|-------|
| `Unknown project "…"` | URL'deki proje adı, tam olarak panonun gösterdiği gibi mi |
| İstemci bağlanıyor ama hiçbir şey bulamıyor | Proje indekslendi mi — pano belge ve parça sayılarını gösterir |
| "indexed with another model" | Projeyi yeniden indeksleyin ([Gömme Modelleri](/tr/docs/embedding-models/)) |
| Local'de çalışıyor, başka bir makineden çalışmıyor | `HOST`, firewall ve `localhost` yerine makinenin adresini kullanıp kullanmadığınız |
| Tarayıcı tabanlı bir istemci reddediliyor | Origin'ini `ALLOWED_ORIGINS`'e ekleyin |
| `401 This project requires an MCP token` | Proje **token required** modunda ve istemci hiç `Authorization` header'ı göndermiyor |
| `401 This project requires an account-backed credential` | Proje **account required** modunda ve istemci hiçbir kimlik bilgisi göndermiyor |
| `401 This project requires an account-backed credential; a static token is not one` | Proje **account required** modunda ve istemci, kimseyi adlandırmayan statik bir `ctxm_…` token gönderiyor |
| `403 That account is not a member of this project` | Connector, projenin üyesi olmayan bir hesap adına oturum açtı. Bu, **open** dâhil **her** modda denetlenir |
| Tarayıcı tabanlı bir connector hiç bağlanamıyor | Bu kurulumda `MCP_OAUTH=0`, yani kullanabileceği bir akış yok |
| `401 Unknown, expired or revoked MCP credential` | Token iptal edilmiş ya da başka bir projeye ait, ya da bir hesap kimlik bilgisinin süresi dolmuş veya sonlandırılmış. Proje sayfasında yeni bir token üretin ya da connector'ı yeniden bağlayın |
| Bir connector'ı onaylarken "No access to this project" sayfası | Oturum açmış hesap, o connector'ın istediği projenin üyesi değil. Bir proje admin'inden hesabı eklemesini isteyin, ya da üye olan bir hesapla oturum açın |
| Connector'ın code exchange'inde `400 invalid_grant` | Kodun verildiği proje artık yok, ya da hesap artık onu okuyamıyor. Erişim geri geldiğinde yeniden bağlanın |

Daha fazlası [Sorun Giderme](/tr/docs/troubleshooting/) sayfasında.
