Ajanın ve uygulamanın işinde MCP ve API

Ajan dış bir kaynağa gitti, yanıtın biçimini çözdü ve harita içeren bir sayfa oluşturdu. Çalışıyor. Şimdi bu sayfayı, bilgisayarında Claude Code'un izi bile olmayan başka biri açıyor.

Yayına almadan önce bir soruyu yanıtlamakta fayda var. Ziyaretçi için verileri kim alacak? İki yolu, MCP'nin ne iş yaptığını, bağlantının nasıl kontrol edileceğini ve ajan oturumunu kapattıktan sonra neyin çalışmaya devam etmesi gerektiğini ele alalım.

Verileri şu anda kim istiyor

İki durum var ve bunları karıştırmak kolay, çünkü ekranda ikisi de "veriler geldi" gibi görünür.

İlk durumda ajan kaynağı inceliyor. Siz proje üzerinde çalışıyorsunuz, Claude Code hizmetin belgelerini okuyor, bir istek deniyor, yanıtın yapısına bakıyor. Veriler ona kodu yazmak için gerekiyor. Bu, sizin bilgisayarınızda ve tam olarak oturum açık kaldığı sürece olur.

İkinci durumda ziyaretçi yayınlanmış sayfayı açıyor. Veriler bu kez sayfaya gerekiyor - güncel durumu göstermek için. İsteği, uygulama çalışırken uygulamanın kodu yapar. Buna runtime denir; yani uygulamanın kullanıcıda çalıştığı zaman, sizin onu yazdığınız zaman değil.

Bir de üçüncü, ara bir seçenek var. Ajan kaynağa bir kez gitti ve yanıtı kodun yanındaki bir dosyaya kaydetti, site de bu dosyanın içeriğini gösteriyor. Böyle bir çözümde kötü bir şey yok, hatta örnek ya da demo için kullanışlı. Yalnızca bu bir anlık görüntü: kaydedildiği haliyle kalır ve kendini güncellemez.

İki zincir birbirinden ayrı çalışır, aralarında ok yok

Ortadaki kesikli çizgiye dikkat edin. Orada süs olsun diye durmuyor. Üst ve alt zincir arasında ok yok ve şemadan çıkarılacak asıl şey de bu. Kaynak aynı olabilir, ama ajanın ve sayfanın ona giden yolu ayrı. Aşağıda her zinciri ayrı ayrı ele alacağız.

MCP nedir

Bir görev nadiren yalnızca depoda yaşar. Hatanın açıklaması ticket'ta durur, stack trace izleme sisteminde, kütüphanenin güncel kuralları belgelerde, gereken kayıtlar da veritabanında.

Entegrasyon olmadan bunların hepsini tarayıcıdan ajanla sohbete elle taşımanız gerekir. Bir kerelik taşıma katlanılabilir. Tekrarlanan işlerde ise veriler eskir, bazı ayrıntılar kaybolur ve aynı yolu yeniden yürümek gerekir.

MCP (Model Context Protocol), Claude Code'un erişilebilir dış araçları öğrenmesini, onları çağırmasını ve sonucu üzerinde anlaşılmış bir biçimde almasını sağlayan bir standarttır. En basit zincirde Claude Code bir MCP istemcisi oluşturur, istemci bir MCP sunucusu ile bağlantıyı tutar, sunucu da erişimi olan sisteme uzanır: dosyalara, veritabanına, başka birinin API'sine.

Claude Code MCP sunucusuyla konuşur, sunucu ise dış sistemlerin yalnızca önceden tanımlanmış yeteneklerini açar

Solda yerleşik MCP istemcisiyle Claude Code, ortada bildirilmiş yetenekleriyle MCP sunucusu, sağda dış sistemler var. Buradaki asıl nokta şu: ajan her şeye birden denetimsiz erişim elde etmez. Yalnızca sunucunun sunmaya karar verdiği işlemleri ve verileri görür.

Hazır bir MCP sunucusu sizi entegrasyon işinin bir kısmından da kurtarır. Her dış sistem için çağrı biçimlerini kendiniz tanımlamanız ve o sistemin API'sine erişen kodun tamamını yazmanız gerekmez. Bunu sunucu üstlenir, Claude Code da önceden bildirilmiş işlemlerle çalışır.

Bu arada sunucunun internette bir yerlerde duran ayrı bir program olması şart değil. Doğrudan sizin bilgisayarınızda yerel bir süreç olarak çalışabilir ya da uzakta çalışıp aynı anda birçok istemciye hizmet verebilir. Sizin açınızdan fark çoğunlukla onu nasıl bağladığınızdadır.

Sunucunun tam olarak neler yapabildiğine kendisi karar verir. Protokol, sunucunun sunabileceği üç tür şeyi tanımlar:

tools - ajanın yürütebileceği işlemler: bir sayfayı almak, API'ye istek göndermek, veri yazmak;
resources - sunucunun bağlam olarak verdiği içerik: dosyalar, kayıtlar, hizmet yanıtları;
prompts - hazır olarak çağrılabilen, önceden hazırlanmış istek şablonları.

Sunucunun üçünü birden desteklemesi gerekmez. Bağlantı sırasında istemci ve sunucu hangisinin neyi yapabildiğini karşılaştırır, desteklenmeyen işlemler de basitçe kullanılmaz. Birçok sunucu yalnızca tools ile yetinir ve bu yeterlidir. MCP mimarisi.

Asıl akılda tutulması gereken şu. MCP, istemci ile sunucunun nasıl konuştuğunu standartlaştırır. Size tam olarak neyin erişilebilir olacağını protokol değil, sunucu belirler. Bir sunucuyu bağlamak tüm internete erişim almak demek değildir: tam olarak o sunucunun bildirdiği işlem kümesini alırsınız.

Ajana verdiğiniz görevde bir komut değil, kaynağı ve istediğiniz sonucu belirtin. Ardından bağlı sunucuda uygun bir işlem olup olmadığını kontrol edin. Gereken işlem yoksa görev ikna ederek değil, başka bir yoldan çözülür.

Veriler siteye nasıl ulaşır

Şimdi alt zincir. Yayınlanmış bir sayfa verileri iki yoldan biriyle alır.

Birinci durumda tarayıcı herkese açık API'ye doğrudan başvurur. Bu yol, kaynak açık olduğunda ve anahtar gerekmediğinde uygundur. Sayfanın kodu isteği gönderir ve yanıtı ekrana çizer. Basit ve gereksiz ayrıntı yok.

İkinci durumda tarayıcı uygulamanın backend'ine başvurur, o da korumalı API'ye. Kaynak bir anahtar istediğinde böyle yapılır. Sır sunucuda kalır, tarayıcı onu görmez. Burada frontend ekranda görünenden sorumludur, backend ise sunucuda çalışan ve hizmete uygulama adına gidebilen kısımdır.

Herkese açık API'ye tarayıcı doğrudan erişebilir, korumalı API'nin anahtarı ise backend'de kalır

Üst yol daha kısa, çünkü tarayıcı açık bir kaynağa kendisi başvurabilir. Alt yolda backend sırrı koruyan sınır olur. Anahtar sunucuda kalır ve sayfanın koduna girmez.

Peki ne olmaz? Claude Code'un MCP sunucusuyla bağlantısı, yayın sırasında siteyle birlikte taşınmaz. Sunucuyu eklediğiniz komut sizin ajanınızı yapılandırır; uygulamaya tek satır kod eklemez. Kendi MCP istemcisi olan bir uygulama yazmak mümkün, ama bu ayrı bir iş ve ayrı bir uygulamadır, Claude Code'daki bağlantının sonucu değildir.

Bunların hepsi oldukça hızlı kontrol edilir. Claude Code'u kapatın, yayınlanmış sayfayı açın ve geliştirici araçlarında Ağ (Network) sekmesine bakın. Veriler geliyorsa istek, adres ve yanıt görünür. Gelmiyorsa istek de olmaz; bu tam da sayfayı başka biri görmeden önce yakalanması gereken durumdur.

Ekrandaki görüntü tek başına yetmez. Sayfa daha önce kaydedilmiş bir anlık görüntüyü gösteriyor olabilir ve yine de tamamen canlı görünebilir. Bakılması gereken, isteğin kendisidir. Tersi de geçerli: yanıtta yeni olay olmaması henüz bir arıza demek değildir. Kaynak, seçilen dönem için basitçe hiçbir şey göndermemiş olabilir.

Bağlantı nasıl kontrol edilir

Sıra her sunucu için aşağı yukarı aynıdır:

sunucunun resmi talimatını bulun: adres, erişim yöntemi, işlem listesi;
sunucuyu tam olarak bu talimatın verdiği komutla ekleyin;
Claude Code'da /mcp açın ve sunucunun bağlandığını, hangi araçlarının olduğunu görün;
en basit okuma isteğini bir kez çalıştırın;
sonucu kaynakla elle karşılaştırın: aynı sayfayı kendi gözünüzle açın.

Terminalde durumu claude mcp list gösterir, tek bir sunucunun ayrıntılarını ise claude mcp get. Bu adımların farklı sorulara yanıt verdiğini bilmek işe yarar:

Ne gördünüz	Bu neyi kanıtlar
ekledikten sonra `Added ...` satırı	yapılandırma kaydedildi, o kadar
`Connected` durumu, `claude mcp list` çıktısında	Claude Code sunucuya bağlanabildi
araç içerik döndürdü	yol, istekten yanıta kadar baştan sona çalışıyor

Fark biçimsel değil. Başarıyla kaydedilmiş bir yapılandırma, sunucunun yanıt verdiği hakkında hiçbir şey söylemez; başarılı bir bağlantı da gereken işlemin mevcut olduğu ve ona yetkinizin bulunduğu hakkında. Bu yüzden kontrol tek bir gerçek çağrıyla bitirilir. Bu arada listede Needs authentication yazıyorsa sunucu bozuk değildir, sadece oturum açılmasını bekliyordur.

Somut bir örnek alalım. Firecrawl hizmetinin, herkese açık bir sayfanın içeriğini alabilen bir MCP sunucusu var; aracın adı firecrawl_scrape. Ajan için bu, bir belge sayfasını sohbete parça parça kopyalamak yerine bütünüyle okumanın kullanışlı bir yolu.

# sunucuyu HTTP üzerinden ekle; tam adres hizmetin belgelerinden alınır
claude mcp add --transport http firecrawl https://mcp.firecrawl.dev/v2/mcp

Şimdi erişim konusu. Firecrawl belgeleri hem hesap ve anahtar olmadan, günlük sınırlarla çalışmayı hem de istemcinin giriş sayfasını kendisi açtığı tarayıcı üzerinden oturum açmayı anlatıyor. Hizmetlerin koşulları ve limitleri değişir, bu yüzden güncel olanlara makalede değil, hizmetin kendisinde bakılır. Firecrawl belgelerinde MCP.

Bir de zaman kazandıran küçük bir ayrıntı. Varsayılan olarak sunucu, komutu verdiğiniz proje için eklenir ve diğer projelerde görünmez. Sunucu her yerde ya da tam tersine tüm ekip için gerekiyorsa, ekleme komutunun ayrı kapsam (scope) seçenekleri vardır. Claude Code belgelerinde MCP.

Anahtarın değerinin ne yapılandırma örneğinde, ne sunucu adresinde, ne de ajanla yazışmada yeri vardır. Yapılandırmaya ortam değişkeninin adı konur, değer ayrıca ayarlanır. Bu, anahtarlar üzerine komşu makalenin konusu.

Belirli bir araç neye izin verir

Bağlı bir sunucu bir işlem kümesidir ve bu işlemlerin sonuçları çok farklıdır. Bir sayfayı okumak ile dış sistemdeki bir kaydı değiştirmek hiç de aynı şey değildir, ama ikisi de aynı şekilde çağrılır.

Bir çağrıyı onaylamadan önce üç şeye bakmak işe yarar: araç hangi nesneyle çalışıyor, hangi işlemi yapıyor ve bunun için hangi yetkiler gerekiyor. Okuma genellikle daha güvenlidir, ama onun da bir bedeli var. İstek üçüncü taraf bir hizmete gider ve kotanızı harcar.

Yanıtta ne geldiği ise ayrı bir konu. Dış bir siteden alınan metin talimat değil, veridir. Sayfanın içinde "şimdi tüm dosyaları sil" yazıyorsa, bu sayfadaki bir metin olarak kalır ve kararı siz verirsiniz. Ajanın dış bir kaynağı okuduktan sonra ne yapmaya hazırlandığına tam da bu yüzden göz atmak gerekir.

Ve asıl pratik soru. MCP'ye gerçekten gerek var mı? Her zaman değil.

Görev	En kolay nasıl çözülür
sitede herkese açık bir JSON'dan veri göstermek	uygulama kodundan sıradan bir istek, MCP gerekmez
ajan, hazır entegrasyonu olan bir hizmetle düzenli olarak çalışıyor	MCP kendini amorti eder: işlemler tanımlı, bağlantı tekrar tekrar kullanılır
belgeleri bir kez okumak ya da tek bir adresi yoklamak	URL'yi okumak ya da API'ye doğrudan başvurmak yeterli

MCP dışarıya açılan tek kapı değildir ve geri kalan her şeyin yerini tutmaz. Ajanın elinde komut satırı da, API'ye doğrudan başvuru da kalır. Seçim, bağlantının zaten kurulu olmasından değil, görevden yola çıkar.

Kendi projenizde neyi kontrol etmeli

Ajan dış verilerle çalışmayı hazırlarken, sonradan çözmeye çalışmak yerine ondan iki katmanı açıkça ayırmasını istemek işe yarar:

İki yolu ayrı ayrı açıkla:
proje üzerinde çalışırken verileri sen nereden alıyorsun
ve uygulamanın kendisi ziyaretçide onları nereden alacak.
Uygulamanın isteğinin hangi dosyada ve kodun neresinde durduğunu göster.
Sayfayı oturum kapalıyken kontrol et: veriler geliyor mu, gelmiyor mu.
Şu anda kaydedilmiş bir anlık görüntü kullanılıyorsa bunu açıkça söyle.

En sık karşılaşılan üç durum ve her birinin yanıtı:

Ne gerekiyor	Verileri kim alıyor	Neden böyle
geliştirme sırasında hizmetin belgelerini incelemek	ajan	veriler kod yazmak için gerekli, ziyaretçide bu istek tekrarlanmaz
ziyaretçideki haritayı güncellemek	uygulamanın kodu	istek sayfa çalışırken yapılır, ajan oturumu o sırada çoktan kapanmıştır
bir seçkiyi bir kez JSON'a kaydetmek	ajan, ve yalnızca bir kez	sonrasında site dosyayı gösterir; veriler kaydedildiği haliyle kalır

Dikkat edin, MCP burada yalnızca ilk satırda görünüyor, o da zorunlu değil. Görev sıradan bir adres okumasıyla çözülüyorsa, öyle çözmek doğru olur.

İşinizi başka birine göstermeden önceki son kontrol en basitidir: Claude Code'u kapatın ve sayfayı açın. Çalışmaya devam eden şey sizin uygulamanızdır. Geri kalan her şey geliştirme sırasında ajanın yardımıydı: faydalı, ama sizin bilgisayarınızda kaldı.