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:
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:
claude mcp add --transport http demo-docs http://localhost:3444/mcp/demo
Çalıştığını kontrol edin:
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:
{
"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:
{
"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:
{
"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:
{
"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
initializeisteğiniPOSTedin; session idmcp-session-idheader’ında geri gelir. - HTTP + SSE (protokol
2024-11-05, eski): URL’yiGETedin; sunucu/mcp/demo/messages?sessionId=…’i işaret eden birendpointolayıyla yanıt verir. Kullanımdan kaldırılmıştır — çalışmaya devam eder, her yanıtDeprecation: @1790899200,Sunset: Sat, 02 Oct 2027 00:00:00 GMTve uyumluluk politikasını gösteren birLinkheader’ı taşır ve yeni istemciler onun üzerine kurulmamalıdır. 2027-10-02’den sonraki ilk1.xminor 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çanGETisteği ve/mcp/demo/messages’a gidenPOST’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.
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 birMcp-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:
initializeyok, oturum yok ve her istek protokol sürümünü ve istemci yeteneklerini bir_metazarfında kendisi taşır. İstemci önce sunucunun hangi protokol sürümlerini ve yeteneklerini sunduğunu öğrenmek içinserver/discoverçağırabilir, sonra doğrudantools/callyapar. İstek, protokol sürümünüMCP-Protocol-Versionbaşlığında, metoduMcp-Methodbaşlığında vetools/call,resources/readileprompts/getiçin araç adını, kaynak URI’sini ya da prompt adınıMcp-Namebaş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ı); 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.
{
"mcpServers": {
"billing-docs": { "url": "http://localhost:3444/mcp/billing" },
"mobile-docs": { "url": "http://localhost:3444/mcp/mobile" }
}
}
Başka bir makineden bağlanmak
- Sunucunun erişilebilir olduğundan emin olun:
HOST=0.0.0.0(varsayılan) ve port açık. localhostdeğil, sunucunun adresini kullanın:http://docs.internal:3444/mcp/demo.- 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.
Bir ajan olmadan doğrulamak
Depoyla birlikte bir smoke test gelir. Bir kaynak checkout’undan:
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:
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) |
| 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 sayfasında.