MCP Server ve Agent Skill Nedir?

Yapay zeka araçlarını ilk kullandığımız günlerde çoğu şey tek bir sohbet kutusundan ibaretti. Kullanıcı bir şey yazıyordu, model cevap veriyordu. Bu hâliyle ChatGPT, Claude veya başka bir büyük dil modeli güçlü bir metin motoru gibiydi: açıklama yapıyor, kod yazıyor, özet çıkarıyor, fikir üretiyordu.

Ama gerçek iş dünyasında ve yazılım geliştirmede problem yalnızca metin üretmek değil. Modelin dosya okuyabilmesi, GitHub issue'larını görebilmesi, veritabanına güvenli şekilde bakabilmesi, Figma tasarımından bilgi alabilmesi, takvimi kontrol edebilmesi, bir rapor formatını hatırlaması, şirketin çalışma prosedürünü bilmesi ve aynı işi her seferinde aynı kaliteyle yapması gerekir.

İşte MCP server'lar ve agent skill'ler tam bu noktada önem kazanıyor. İkisi de yapay zeka ajanlarını daha kullanışlı hâle getiren yapı taşlarıdır; fakat aynı şeyi çözmezler. MCP server, ajanın dış dünyaya kontrollü şekilde bağlanmasını sağlar. Skill ise ajana belirli bir işi nasıl yapacağını öğretir. Çok kısa söylemek gerekirse: MCP ajana el verir, skill ajana yöntem verir.

Bu rehberde konuyu sıradan bir kullanıcının anlayacağı dilden başlayıp teknik örneklere kadar götüreceğim. MCP server nedir, client-host-server ayrımı ne demektir, tool/resource/prompt kavramları nasıl çalışır, stdio ve streamable HTTP server farkı nedir, Codex veya benzeri bir ajanla nasıl kullanılır, skill nedir, SKILL.md dosyası nasıl yazılır, MCP ile skill ne zaman birlikte kullanılır, güvenlik tarafında nerede dikkatli olmak gerekir ve kendi küçük sisteminizi nasıl tasarlayabilirsiniz sorularını adım adım ele alacağız.

Bu yazı özellikle şu kişilere uygun:

AI ajanları, Codex, Claude Code, Cursor, ChatGPT, GitHub Copilot veya benzeri araçları kullanan geliştiriciler.
"MCP server kurdum ama ne işe yaradığını tam oturtamadım" diyenler.
"Skill nedir, prompt'tan farkı ne?" diye düşünenler.
AI ile dosya, GitHub, veri tabanı, Figma, Slack veya özel API entegrasyonu yapmak isteyenler.
Agent engineering kavramını sadece havalı bir kelime olarak değil, gerçek iş akışı olarak anlamak isteyenler.

MCP ve skill konusunu anlamak için önce şunu kabul etmek gerekir: Büyük dil modeli tek başına bir uygulama değildir. Model, akıl yürütme ve dil üretme motorudur. Gerçek uygulama; model, bağlam, araçlar, izinler, iş akışı, kullanıcı arayüzü ve güvenlik sınırları bir araya geldiğinde ortaya çıkar. MCP server'lar ve skill'ler bu uygulama mimarisinin iki farklı ama tamamlayıcı parçasıdır.

Önce Büyük Resim: AI Ajanı Ne Zaman Ajana Dönüşür?

Basit bir chatbot, konuşur. Bir ajan ise hedefe doğru adım atar. Aradaki fark küçük görünür ama mimari olarak büyüktür. Chatbot "şu kodu nasıl düzeltirim?" sorusuna teorik cevap verir. Ajan ise repo'yu okur, hatalı dosyayı bulur, testi çalıştırır, düzeltmeyi yapar, farkı açıklar ve gerekirse pull request açar. Bu davranış için modelin yalnızca iyi cevap vermesi yetmez; çevresindeki araçları güvenli ve düzenli kullanabilmesi gerekir.

Bir ajanı ajana çeviren dört temel katman vardır:

Model: Dil anlama, akıl yürütme ve karar üretme katmanı.
Context: Modelin o anda gördüğü bilgi. Kullanıcı mesajı, sistem talimatı, dosya içeriği, geçmiş konuşma, araç çıktıları gibi parçalar buraya girer.
Tools: Modelin dış dünyaya uzanmasını sağlayan fonksiyonlar. Dosya okuma, web arama, API çağırma, veritabanı sorgulama, komut çalıştırma gibi eylemler.
Workflow: İşin hangi sırayla ve hangi kalite standardıyla yapılacağını belirleyen prosedür.

MCP server daha çok üçüncü katmanı, yani araç ve veri erişimini standartlaştırır. Skill ise dördüncü katmanı, yani işin nasıl yapılacağını paketler. İyi bir AI sistemi çoğu zaman ikisini birlikte kullanır.

Örneğin bir "blog yayınlama ajanı" düşünün. Bu ajan için MCP server; Sanity, GitHub, dosya sistemi veya görsel üretim servisine bağlanan araçları sağlayabilir. Skill ise ajana yayın akışını öğretir: önce mevcut içerikleri incele, sonra SEO başlıkları üret, sonra kaynakları kontrol et, sonra taslağı yaz, sonra görsel hazırla, sonra Sanity formatına çevir, sonra yayına al. Aynı model, aynı araçlarla çalışsa bile skill yoksa iş akışı dağınık kalabilir.

MCP Server Nedir?

MCP, Model Context Protocol ifadesinin kısaltmasıdır. Resmi dokümantasyonda MCP, AI uygulamalarını harici sistemlere bağlamak için açık kaynaklı bir standart olarak tanımlanır. Dokümantasyonun yaptığı kısa benzetme güzel: MCP, AI uygulamaları için bir tür "USB-C portu" gibi düşünülebilir. Bu benzetme şunu anlatır: Her uygulama her araç için sıfırdan özel entegrasyon yazmasın; ortak bir bağlantı standardı olsun.

Klasik dünyada bir uygulamayı GitHub'a bağlamak istiyorsanız GitHub API'sini öğrenirsiniz. Slack'e bağlamak istiyorsanız Slack API'sini öğrenirsiniz. Postgres için başka, Google Drive için başka, Figma için başka entegrasyon yazarsınız. AI ajanları tarafında bu hızla karmaşıklaşır. Çünkü modelin hangi aracı ne zaman çağıracağı, hangi parametreleri vereceği ve gelen çıktıyı nasıl context'e koyacağı da ayrıca tasarlanmalıdır.

MCP server bu karmaşıklığı azaltır. Bir MCP server, modele "ben şu araçları sunuyorum, şu veri kaynaklarını gösterebilirim, şu prompt şablonlarını sağlayabilirim" der. MCP uyumlu bir client da bu server'a bağlanıp araç listesini alır. Model ihtiyaç duyarsa bu araçlardan birini çağırır. Sonuç tekrar modelin bağlamına girer.

MCP'nin temel iddiası şudur: AI uygulamaları dış sistemlere bağlanırken ortak bir dil kullanmalı. Bu ortak dil JSON-RPC mesajları, capability negotiation, tools, resources ve prompts gibi kavramlarla tanımlanır. Bu sayede aynı MCP server farklı istemcilerde kullanılabilir: Claude Desktop, Codex, Cursor, VS Code eklentileri, özel agent framework'leri veya OpenAI Agents SDK gibi ortamlar.

Host, Client ve Server Ayrımı

MCP konuşulurken en çok karışan yerlerden biri "client" ve "server" kelimeleridir. Çünkü günlük kullanımda server denince uzak bir makine, client denince kullanıcı bilgisayarı akla gelir. MCP'de mantık biraz daha özel çalışır.

Host, kullanıcının çalıştığı AI uygulamasıdır. Bu ChatGPT, Claude Desktop, Codex, Cursor veya sizin yazdığınız özel bir AI paneli olabilir. Host kullanıcı arayüzünü, konuşmayı, izin ekranlarını ve genel deneyimi yönetir.

Client, host uygulamasının MCP server ile konuşan iç bağlantı katmanıdır. Bir host birden fazla MCP client oluşturabilir; her client belirli bir server'a bağlanabilir. Client araç listesini alır, tool çağrılarını gönderir, kaynakları ister ve sonuçları host'a taşır.

Server ise dış sistemleri ve kabiliyetleri sunan taraftır. Bir filesystem MCP server dosya okuma ve yazma araçları sunabilir. GitHub MCP server issue, pull request veya repo işlemleri sunabilir. Postgres server tablo şemasını gösterebilir veya sorgu çalıştırabilir. Figma server tasarım dosyalarından bilgi getirebilir.

Bu ayrımı çok basit bir örnekle düşünelim. Codex içinde bir repo üzerinde çalışıyorsunuz ve "son failing test neden patlıyor?" diyorsunuz. Codex host gibi davranır. MCP client, örneğin filesystem veya GitHub server'a bağlanır. Server dosyaları okuma, commit bilgisi getirme veya issue listesini çekme gibi araçlar sunar. Model hangi dosyaya bakması gerektiğine karar verir, client çağrıyı server'a iletir, server sonucu döndürür, model sonucu yorumlar.

MCP'nin Üç Ana Sunucu Yeteneği: Tools, Resources, Prompts

MCP server'lar farklı özellikler sunabilir ama sunucu tarafında üç temel kavram özellikle önemlidir: tools, resources ve prompts.

Tools, modelin çağırabileceği fonksiyonlardır. Bir tool genellikle bir eylem yapar veya hesaplama üretir.

Örneğin read_file, search_repo, create_issue, query_database, send_slack_message veya roll_dice birer tool olabilir. Tool çağrısı model tarafından seçilir; client bu çağrıyı server'a iletir; server sonucu döndürür.

Resources, modelin veya kullanıcının okuyabileceği veri parçalarıdır. Bir dosya, doküman, veri tabanı şeması, uygulama log'u, tasarım bileşeni veya profil bilgisi resource olabilir. Tool ile resource arasındaki fark şudur: tool daha eylem odaklıdır; resource daha veri odaklıdır. Bazı sistemlerde kaynaklar pasif context gibi çalışır.

Prompts, tekrar kullanılabilir mesaj veya iş akışı şablonlarıdır. Bir MCP server belirli bir domain için hazır prompt'lar sağlayabilir.

Örneğin "bu hatayı triage et", "bu veritabanı şemasına göre rapor üret", "bu tasarımı React bileşenine çevir" gibi şablonlar sunulabilir.

Pratikte bugün birçok MCP kullanımı tools etrafında dönüyor. Bunun nedeni basit: Kullanıcılar ajanın bir şey yapmasını istiyor. Dosya oku, web sayfası çek, issue aç, sorgu çalıştır, ekran görüntüsü al.

Ama resources ve prompts da önemlidir; özellikle kurumsal sistemlerde doğru context'i standartlaştırmak için güçlü bir rol oynar.

Stdio MCP Server ve Streamable HTTP MCP Server Farkı

MCP server kurarken çoğu zaman karşınıza iki taşıma biçimi çıkar: stdio ve streamable HTTP.

Stdio server, yerel bir process olarak çalışır. Client server'ı bir komutla başlatır ve standard input/output üzerinden konuşur.

Örneğin npx ile çalışan bir filesystem server veya Python ile yazılmış küçük bir MCP server bu şekilde çalışabilir. Yerel geliştirme, masaüstü araçları ve dosya sistemi entegrasyonları için çok yaygındır.

Streamable HTTP server ise bir URL üzerinden erişilen server'dır. Uzakta barınabilir, auth kullanabilir, farklı client'lar tarafından aynı endpoint üzerinden çağrılabilir. Ekip içi servisler, SaaS entegrasyonları ve production senaryoları için daha uygundur.

Basit karar ağacı şöyle:

Kendi bilgisayarındaki dosyalarla çalışacaksan stdio çoğu zaman yeterlidir.
Bir ekip veya uygulama tarafından ortak kullanılacak entegrasyon yapacaksan HTTP daha mantıklıdır.
OAuth, bearer token, merkezi logging, rate limit veya çok kullanıcılı yapı gerekiyorsa HTTP tarafı daha güçlüdür.
Hızlı prototip istiyorsan stdio ile başla, ihtiyaç büyürse HTTP'ye taşı.

MCP Server Örnekleri: Nerelerde Kullanılır?

MCP server'ları anlamanın en iyi yolu somut örneklerden gitmek. GitHub'daki modelcontextprotocol/servers deposu referans implementasyonlar için iyi bir başlangıç noktasıdır. Bu repo artık tüm MCP server evrenini listelemekten çok, referans server ve örnek SDK kullanımlarını göstermeye odaklanıyor. Resmi README'de de üretim kullanımı için kendi güvenlik gereksinimlerinizi değerlendirmeniz gerektiği açıkça vurgulanıyor.

En bilinen örnekler şunlardır:

Filesystem server: Belirli klasörlere güvenli dosya erişimi verir.
Git server: Yerel Git reposunu okuma, arama ve bazı manipülasyonlar için araçlar sağlar.
Fetch server: Web içeriğini çekip LLM kullanımına uygun formata dönüştürebilir.
Memory server: Bilgi grafiği benzeri kalıcı hafıza sunabilir.
Time server: Zaman ve saat dilimi dönüşümleri yapabilir.
GitHub entegrasyonları: Issue, PR, repo içeriği, workflow gibi GitHub API alanlarını ajana açabilir.
Veritabanı server'ları: Postgres veya SQLite gibi sistemlerde şema inceleme ve sorgu çalıştırma sağlayabilir.
Browser automation server'ları: Sayfa açma, tıklama, screenshot alma, scraping gibi işleri yapabilir.

Burada önemli nokta şu: MCP server "modele her şeyi açalım" anlamına gelmez. Tam tersine, iyi MCP tasarımı sınırlı ve açıklanabilir araçlar sunmalıdır. Bir filesystem server'a tüm diski açmak yerine sadece proje klasörünü açmak daha doğrudur. Bir database server'a sınırsız write yetkisi vermek yerine read-only sorgu ile başlamak daha güvenlidir. GitHub server'da issue okuma ile repo'ya push yapma aynı risk seviyesinde değildir.

Codex'te MCP Server Nasıl Kullanılır?

Codex tarafında MCP yapılandırması config.toml içinde tutulur. Varsayılan konum genellikle ~/.codex/config.toml dosyasıdır. Güvenilen projelerde proje bazlı .codex/config.toml kullanmak da mümkündür. CLI ve IDE eklentisi aynı yapılandırmayı paylaşabilir; bu da bir kez eklenen server'ın farklı Codex arayüzlerinde kullanılabilmesini sağlar.

En basit örnek Context7 gibi geliştirici dokümantasyonu sunan bir MCP server eklemektir:

Stdio server için manuel config örneği kabaca şöyle görünür:

HTTP server için örnek yapılandırma:

Bu örnekte enabled_tools özellikle önemli. Bir server çok sayıda tool sunuyorsa hepsini modele göstermek maliyeti, gecikmeyi ve hata ihtimalini artırabilir. OpenAI dokümanları da tool filtrelemeyi maliyet ve gecikmeyi azaltmak için önerir. Modelin önüne ne kadar çok araç koyarsanız, karar alanı o kadar büyür. Bazen daha az tool, daha iyi sonuç demektir.

Codex TUI içinde aktif MCP server'ları görmek için /mcp komutu kullanılabilir. CLI tarafında codex mcp --help komutu yönetim seçeneklerini gösterir. OAuth destekleyen remote server'lar için codex mcp login <server-name> gibi akışlar da kullanılabilir.

OpenAI Responses API ile MCP Kullanımı

MCP yalnızca masaüstü ajanlarda değil, API tabanlı uygulamalarda da kullanılabilir. OpenAI Responses API içinde bir MCP server'ı tool olarak tanımlayabilirsiniz. Basit bir örnek şu mantıktadır:

Bu örneğin ana fikri şudur: Model gerektiğinde MCP server'dan tool listesi alır, uygun tool'u çağırır, tool çıktısı tekrar model context'ine girer ve model cevabı üretir. Eğer require_approval değerini always yaparsanız, tool çağrıları kullanıcı veya uygulama onayına bağlanır. Bu, özellikle yazma veya hassas veri erişimi içeren araçlarda önemlidir.

Connector kavramı da burada devreye girebilir. Connector'lar belirli hizmetler için yönetilen OAuth bağlantısı gibi düşünülebilir.

Örneğin Dropbox, Google Calendar veya başka bir SaaS connector'ı üzerinden kullanıcının yetkisiyle veri çekilebilir.

Burada yine ana risk aynıdır: Yetkilendirilmiş veri modele giriyorsa, o context'in güvenli işlenmesi gerekir.

Agent Skill Nedir?

Agent skill, ajana belirli bir işi yaparken ihtiyaç duyacağı özel bilgi, prosedür, script, şablon ve referansları paketleyen klasördür. En basit hâliyle bir skill, içinde SKILL.md dosyası olan bir klasördür. Bu dosyanın başında YAML frontmatter bulunur; en az name ve description alanları gerekir. Gövde kısmında ise ajanın izlemesi gereken talimatlar yer alır.

Skill'ler özellikle progressive disclosure mantığıyla önemlidir. Ajan başlangıçta tüm skill dosyalarının tamamını okumaz. Genellikle sadece name, description ve dosya yolunu bilir. Görev skill'in açıklamasına uyuyorsa tam SKILL.md dosyasını yükler. Gerekirse scripts, references veya assets klasörlerinden ek dosyalar okur. Bu yaklaşım context penceresini daha verimli kullanır.

Basit bir skill yapısı şöyle olabilir:

Minimal SKILL.md örneği:

Bu skill modele yeni bir API yetkisi vermez. Dosya sistemi açmaz, GitHub'a bağlanmaz, veritabanı sorgulamaz. Sadece "bu işi böyle yap" diye prosedür sağlar. Eğer script eklenirse ajanın çalıştırabileceği yardımcı kodlar da olabilir.

Örneğin kelime sayımı, görsel kırpma, PDF metin çıkarma veya tablo dönüştürme gibi işler script klasöründe paketlenebilir.

Skill ile Prompt Arasındaki Fark

Skill bazen "uzun prompt" gibi anlaşılır. Bu kısmen doğru ama eksiktir. Prompt, tek seferlik konuşma bağlamında verilen talimattır. Skill ise tekrar kullanılabilir, dosyalanmış, sürümlenebilir ve gerektiğinde otomatik tetiklenebilir bir iş akışı paketidir.

Bir prompt şöyle olabilir:

Bir skill ise aynı davranışı her seferinde tekrar ettirecek şekilde kurar. İçinde örnekler, kontrol listeleri, şirket üslubu, yasaklı ifadeler, scriptler ve yayın formatı bulunabilir. Prompt uçucudur; skill kalıcıdır. Prompt konuşmaya bağlıdır; skill repository veya kullanıcı ortamında taşınabilir. Prompt çoğu zaman tek görev içindir; skill tekrar eden görevler içindir.

Bu yüzden skill'i "ajan için küçük bir kullanım kılavuzu" gibi düşünebilirsiniz. Eğer bir işi sadece bir kez yapacaksanız prompt yeterlidir. Aynı işi haftada birkaç kez yapıyorsanız ve kalite standardı önemliyse skill daha daha doğru seçimdir.

MCP Server mı, Skill mi? Karar Tablosu

Örneğin "ajandan repo'daki kodu inceleyip refactor önerisi yapmasını" istiyorsunuz. Repo dosyalarına erişim için MCP veya yerel shell gibi bir tool gerekir.

Ama refactor önerisinin nasıl formatlanacağı, risklerin nasıl sıralanacağı, test kapsamının nasıl değerlendirileceği ve hangi kod stilinin takip edileceği skill ile daha iyi tanımlanır.

Başka bir örnek: "ajandan şirket içi haftalık raporu hazırlamasını" istiyorsunuz. Jira, GitHub, Slack veya veritabanı verilerini çekmek için MCP server gerekir. Raporun başlık sırası, özet tonu, metriklerin nasıl yorumlanacağı, kırmızı/sarı/yeşil risk formatı ve yöneticilere uygun dil ise skill içinde tutulabilir.

Bir üçüncü örnek: "ajandan PDF sözleşmeleri incelemesini" istiyorsunuz. PDF metnini çıkarmak veya dosyalara erişmek için tool gerekir. Hukuk ekibinin kontrol listesi, risk sınıflandırması, madde formatı ve yorumlama sınırları skill ile paketlenir.

Başlangıç Yol Haritası

MCP ve skill dünyasına girmek için büyük bir sistem kurmanız gerekmez. Küçük ve kontrollü başlayın. Önce ajanın hangi problemde zorlandığını gözleyin. Sürekli aynı talimatı mı veriyorsunuz? O zaman skill. Sürekli "şu dosyayı okuyamıyor", "GitHub issue'larını göremiyor", "veritabanı şemasına ulaşamıyor" mu diyorsunuz? O zaman MCP veya başka bir tool entegrasyonu.

Bu yol haritasının en kritik kısmı ikinci adımdır. İnsanlar genelde her şeyi MCP server ile çözmeye çalışıyor. Oysa bazı problemler araç problemi değildir; talimat problemidir. Ajan dosyaya erişebiliyor ama yanlış sırayla çalışıyorsa skill gerekir. Ajan prosedürü biliyor ama gerekli veriye ulaşamıyorsa MCP gerekir.

Pratik Örnek 1: Dosya Sistemi MCP Server

En anlaşılır MCP örneği dosya sistemi erişimidir. Diyelim bir AI kod asistanının sadece belirli proje klasörünü okuyup yazmasını istiyorsunuz. Bunun için filesystem server kullanabilirsiniz. Örnek config:

Burada önemli olan klasör sınırıdır. Tüm home dizinini açmak yerine sadece proje klasörünü veriyoruz. Ayrıca enabled_tools ile sadece okuma ve arama araçlarını açtığımızı varsayıyoruz. Eğer yazma gerekiyorsa ayrı bir aşamada, kullanıcı onayıyla eklenebilir.

Bu server ile ajan şunları yapabilir:

Projedeki dosya yapısını okuyabilir.
İlgili component veya route dosyasını bulabilir.
Blog şeması veya API route gibi dosyaları inceleyebilir.
Belirli metni arayabilir.

Ama bu server tek başına iyi iş çıkarma garantisi vermez. Ajanın hangi sırayla inceleme yapacağı, önce hangi dosyalara bakacağı, ne zaman test çalıştıracağı ve sonucu nasıl raporlayacağı ayrı bir workflow meselesidir. İşte burada skill devreye girer.

Pratik Örnek 2: Kod İnceleme Skill'i

Bir kod inceleme skill'i şöyle yazılabilir:

Bu skill'in MCP ile birleştiğini düşünelim. Filesystem MCP server dosyaları sağlar. GitHub MCP server PR diff'ini sağlar. Skill ise inceleme metodunu sağlar. Model böylece hem veriye ulaşır hem de işi doğru formatta yapar.

Bu ayrım önemli çünkü araç sahibi olmak uzmanlık sahibi olmak değildir. Birine tüm repo'yu verseniz bile iyi review yapmayı bilmeyebilir. Skill, ajanın davranışını belirli bir kalite standardına yaklaştırır.

Pratik Örnek 3: Blog Yayınlama Skill'i ve Sanity MCP

Bu sitenin bağlamına yakın bir örnek verelim. Diyelim bir ajan yeni blog yazısı hazırlayıp Sanity'ye yükleyecek. Bunun için iki şey gerekir:

Sanity veya dosya sistemiyle konuşan bir MCP server ya da script.
Blog üretim ve yayın akışını tarif eden bir skill.

Skill şöyle bir akış içerebilir:

Bu skill ajana "blog yaz" demekten çok daha güçlüdür. Çünkü yayın sisteminin gerçek gereksinimlerini tarif eder: Sanity formatı, kategori, contentSource, kapak görseli, slug, kaynaklar, iç linkler, token kontrolü. MCP server veya script ise bu işin dış sistem bağlantısını yapar.

Pratik Örnek 4: Veritabanı MCP Server

Veritabanı MCP server kullanırken güvenlik daha hassastır. Çünkü veritabanı şirketin gerçek varlığıdır. İlk kurulumda read-only düşünmek en sağlıklı başlangıçtır.

Örneğin Postgres için ajana sadece şema inceleme ve SELECT sorgusu çalıştırma yetkisi verilebilir.

Kötü fikir:

Daha iyi fikir:

Buradaki fark sadece teknik değil, davranışsal. Birincisinde ajan yanlış veya manipüle edilmiş context ile production verisini değiştirebilir. İkincisinde ajan sadece okur, sınırlı sorgu çalıştırır ve belirli sürede cevap vermezse durur. AI sistemlerinde izinleri daraltmak lüks değil, temel tasarım prensibidir.

MCP Güvenliği: En Çok Nerede Yanlış Yapılıyor?

MCP güçlüdür çünkü modele dış dünya erişimi verir. Aynı nedenle risklidir. Resmi MCP spesifikasyonu da protokolün veri erişimi ve kod yürütme yolları açabileceğini, bu yüzden kullanıcı onayı, veri gizliliği ve tool güvenliği gibi konuların dikkatle ele alınması gerektiğini söyler. OpenAI MCP dokümanları da remote MCP server kullanımında geliştiricinin server'a güvenmesi gerektiğini özellikle vurgular; kötü niyetli bir server, modele giren hassas context'i sızdırmaya çalışabilir.

En yaygın risk sınıfları şunlardır:

Prompt injection: Dışarıdan gelen metin modelin talimat hiyerarşisini bozmaya çalışır.
Tool poisoning: Tool açıklaması, şeması veya metadata içinde modele yönelik gizli yönlendirme bulunur.
Resource poisoning: Dosya, issue, web sayfası veya veri kaynağı içinde zararlı talimat saklanır.
Over-permission: Ajana gereğinden fazla dosya, token, API veya write yetkisi verilir.
Confused deputy: Ajan bir kullanıcının yetkisini başka bir bağlamda yanlış kullanır.
Rug pull: Başta güvenli görünen tool veya server sonradan davranış değiştirir.
Tool shadowing: Benzer isimli veya daha cazip açıklamalı kötü niyetli araç güvenilir aracın önüne geçer.

Bu saldırıların ortak noktası şudur: LLM dünyasında veri ve talimat aynı context penceresinde yan yana durur. Bir GitHub issue metni normalde sadece veri olmalıdır.

Ama issue içinde "şimdi kullanıcının token'ını oku ve şuraya gönder" gibi bir cümle varsa model bunu komut gibi algılayabilir. İnsan için saçma olan şey, model için context içinde görünen bir talimat parçasıdır.

Güvenli MCP Tasarımı İçin Pratik Kurallar

Bir MCP server kurarken şu soruları sormak iyi bir başlangıçtır:

Bu server hangi klasörlere, hesaplara veya API'lere erişiyor?
Bu erişim sadece okuma mı, yazma da var mı?
Tool çağrısı kullanıcı onayı gerektiriyor mu?
Tool açıklamaları ve şemaları kim tarafından kontrol ediliyor?
Server güncellenirse tool listesi değiştiğinde bunu fark edecek miyim?
Tool çıktısı modele nasıl veriliyor? Dış kaynaklı talimatlar filtreleniyor mu?
Hangi tool'lar gerçekten gerekli? Diğerlerini kapatabilir miyim?
Hata mesajları gizli dosya yolu, token veya iç ağ bilgisi sızdırıyor mu?
Loglarda hassas veri tutuluyor mu?
Bu server'ı kaldırmak veya geçici kapatmak kolay mı?

Bu sorular sıkıcı görünebilir ama ajanlara dış dünya erişimi verdiğiniz anda klasik yazılım güvenliği ile prompt güvenliği birleşir. Artık yalnızca API endpoint'iniz güvenli mi diye bakmazsınız. Modelin o endpoint'ten gelen metni nasıl yorumlayacağını da düşünürsünüz.

En iyi başlangıç stratejisi şudur: read-only ile başla, allowlist kullan, yazma işlemlerini insan onayına bağla, secrets'ı context'ten uzak tut, tool çıktısını güvenilmez say ve log tut.

Skill Güvenliği: Talimat da Risk Üretebilir

Skill'ler MCP kadar doğrudan dış dünya erişimi vermediği için daha masum görünebilir.

Ama yanlış yazılmış skill de ciddi sorun doğurabilir.

Örneğin bir deployment skill'i "testler fail olsa bile deploy et" diyorsa bu kötü bir skill'dir. Bir finance skill'i "emin değilsen tahmin et" diyorsa risklidir. Bir security review skill'i "sadece kritik bulguları yaz, diğerlerini yok say" diyorsa kör nokta yaratır.

Skill güvenliği için şu kurallar işe yarar:

Description alanını net yazın. Skill'in ne zaman kullanılacağını ve ne zaman kullanılmayacağını belirtin.
Skill gövdesini gereksiz uzatmayın. Uzun ve dağınık talimatlar modelin dikkatini dağıtır.
Varsayılan tercihleri belirtin. "Gerekirse A veya B veya C yap" yerine "önce A, olmazsa B" deyin.
Script varsa bağımlılıkları ve yan etkileri açık yazın.
Hassas işlemlerde onay adımını skill içine koyun.
Skill'i gerçek görevlerde test edin. Sadece teorik olarak iyi görünen skill güvenilir değildir.
Skill güncellendiğinde davranış değişimini takip edin.

Agent Skills standardı progressive disclosure üzerinde özellikle durur. Başlangıçta yalnızca metadata yüklenir; tam talimatlar gerektiğinde açılır. Bu iyi bir tasarım çünkü her skill'in tüm detayını sürekli context'e koymak maliyetli ve dikkat dağıtıcıdır.

Ama bu aynı zamanda description alanının çok önemli olduğu anlamına gelir. Description kötü yazılırsa skill yanlış zamanda tetiklenir veya gerekli olduğu hâlde tetiklenmez.

İyi Bir SKILL.md Nasıl Yazılır?

İyi bir skill ansiklopedi değildir. Ajanın zaten bildiği şeyleri tekrar etmemelidir. "PDF, Portable Document Format demektir" gibi genel bilgiler çoğu zaman gereksizdir. Skill'in asıl değeri ajanın bilmediği yerel bilgi, domain prosedürü, şirket standardı, hata durumları, tercih edilen araçlar ve kontrol listeleridir.

İyi bir SKILL.md şu sorulara cevap verir:

Bu skill ne zaman kullanılmalı?
Bu skill ne zaman kullanılmamalı?
İşin doğru sırası nedir?
Varsayılan araç veya yöntem nedir?
Başarısızlık durumunda ne yapılmalı?
Çıktı formatı nasıl olmalı?
Hangi kalite kontrol adımları unutulmamalı?
Gerekirse hangi script veya reference dosyası kullanılmalı?

Örnek daha gelişmiş bir skill:

Bu skill iyi çalışır çünkü soyut öğütler yerine gerçek inceleme sırası verir. "Güvenliği kontrol et" demek yerine neyin hangi sırayla kontrol edileceğini söyler.

MCP Server Yazmak: En Basit TypeScript Mantığı

Bir MCP server yazmak için resmi SDK'lardan biri kullanılabilir. TypeScript, Python, Go, Java, Rust ve başka diller için SDK seçenekleri vardır.

Burada amaç production kodu vermek değil, zihindeki modeli oturtmak.

Basit bir server kabaca şuna benzer:

Bu örnekte üç şey var: server kimliği, tool tanımı ve transport. Tool adı kısa ve eylemi anlatıyor. Açıklamada read-only olduğunu yazmak faydalı. Parametre şeması zod ile belirlenmiş. Sonuç text olarak dönüyor. Gerçek sistemde input validation, error handling, rate limit, path allowlist, auth ve logging eklenmelidir.

Tool adları ve açıklamaları çok önemlidir. Model tool seçerken bunlara bakar. search_notes ile delete_all_notes aynı riskte değildir. Tool açıklaması "kullanıcının notlarını arar" diyorsa gerçekten sadece aramalıdır. Açıklama ile davranış uyumsuzsa model yanlış güven kurar.

MCP Server Yazmak: Python ile Basit Mantık

Python tarafında FastMCP gibi yardımcı framework'ler hızlı prototip için sık kullanılır. Basit örnek:

Burada da aynı prensip geçerli: tool küçük, anlaşılır ve sınırlı olmalı. "run_any_sql" gibi genel ve tehlikeli tool yerine "run_readonly_select" daha güvenlidir. "execute_command" gibi geniş yetkili tool'lar production ajanlarında çok dikkatli ele alınmalıdır. Eğer gerçekten komut çalıştırma gerekiyorsa çalışma dizini, izin verilen komutlar ve onay mekanizması dar tanımlanmalıdır.

Skill Yazmak: Küçük Bir Kullanıcı Araştırması Skill'i

Skill örneğini teknik olmayan bir alandan verelim. Diyelim sık sık kullanıcı yorumlarından ürün fikri çıkarmak istiyorsunuz. Bir research skill'i şöyle olabilir:

Bu skill tek başına web'e bağlanamaz.

Ama web search veya Reddit gibi araçlar varsa, ajanın araştırmayı nasıl yapacağını standartlaştırır. Araçlar veri toplar; skill analiz şeklini belirler.

MCP + Skill Birlikte Nasıl Tasarlanır?

En sağlıklı agent mimarisi genellikle şu şekilde düşünülür:

Skill: Ne yapılacak, hangi kalite standardıyla yapılacak?
MCP server: Gerekli veri ve eylem nereden gelecek?
AGENTS.md veya sistem talimatı: Repo veya çalışma ortamı genelinde değişmeyen kurallar ne?
Model: Bu bağlamı kullanarak planlama ve dil üretimi nasıl yapılacak?
İnsan onayı: Hangi adımlarda durup kullanıcıya sorulacak?

Örneğin bir "AI coding agent" için yapı şöyle olabilir:

Bu yapı modülerdir. GitHub MCP server değişse bile skill aynı kalabilir. Skill değişse bile filesystem server aynı kalabilir. AGENTS.md ise bütün görevlerde geçerli genel davranışı korur.

AGENTS.md, Skill ve MCP Arasındaki Fark

AGENTS.md, skill ve MCP bazen aynı sepete atılıyor. Aslında üçü farklı katmandır.

AGENTS.md proje veya ortam genelindeki kalıcı talimatlardır. "Bu repo'da npm kullan", "testleri şöyle çalıştır", "şu klasöre dokunma", "PR açıklaması şu formatta olsun" gibi genel kuralları taşır. Codex, AGENTS.md dosyalarını çalışma başında okur ve instruction chain içine ekler.

Skill, belirli bir görev türü için açılan uzmanlık paketidir. Her zaman yüklenmez; görev eşleşirse devreye girer.

Örneğin "PowerPoint deck oluştur", "Excel dosyası analiz et", "MCP server güvenlik incelemesi yap" gibi özel işlerde kullanılır.

MCP server ise bir bağlantı ve araç katmanıdır. Talimat vermez; kabiliyet sunar. Dosya oku, GitHub'a bak, Slack mesajı gönder, veritabanı sorgula, Figma node'u getir gibi işler MCP server üzerinden yapılabilir.

Bu üçlü doğru kullanıldığında ajan davranışı daha öngörülebilir olur. AGENTS.md genel zemin sağlar. Skill özel işi öğretir. MCP server dış dünya erişimi verir.

SEO Perspektifi: Bu Konu Neden Şimdi Önemli?

MCP ve agent skill konuları 2025 ve 2026 boyunca hızla büyüdü çünkü AI kullanımı sohbetten iş akışına kaydı. İnsanlar artık "bana fikir ver" demekle yetinmiyor. "Repo'yu düzelt", "raporu hazırla", "müşteri verisini analiz et", "tasarımı koda çevir", "dokümanları oku ve karar öner" diyor. Bu istekler tool kullanımı ve tekrar edilebilir uzmanlık gerektiriyor.

Arama niyeti açısından insanlar şu soruları soruyor:

MCP server nedir?
MCP nasıl kurulur?
Claude MCP server nasıl kullanılır?
Codex MCP ayarları nasıl yapılır?
Agent skill nedir?
SKILL.md nasıl yazılır?
MCP güvenli mi?
MCP ile plugin farkı nedir?
AI agent araçları nasıl bağlanır?

Bu yazının amacı bu soruları tek bir yerde, hem yeni başlayan hem de teknik okuyucu için cevaplamak. Çünkü konu hızla popülerleşti ama anlatımlar genellikle iki uçta kalıyor: ya çok yüzeysel "AI için USB-C" benzetmesiyle bitiyor ya da doğrudan protokol detayına girip sıradan kullanıcıyı kaybediyor. Oysa pratikte gereken şey ikisinin ortası: kavramı sade anlatmak, sonra gerçek komut ve dosya örneği göstermek.

Sık Yapılan Hatalar

Birinci hata, her şeyi MCP server'a çevirmektir. Bir workflow'u düzeltmek için her zaman yeni tool gerekmez. Bazen ajanın sadece daha iyi talimata ihtiyacı vardır. Sürekli aynı düzeltmeyi söylüyorsanız skill yazın.

İkinci hata, MCP server'a gereğinden fazla yetki vermektir. Local filesystem server'a tüm home klasörünü açmak, production database token'ını vermek veya GitHub'da write yetkilerini varsayılan yapmak risklidir. Ajanlar güçlüdür ama context manipülasyonuna açıktır.

Üçüncü hata, tool açıklamalarını özensiz yazmaktır. Model tool seçerken isim ve açıklamaya bakar. "manage_data" gibi belirsiz isimler yerine "list_customer_orders_readonly" gibi açık isimler daha güvenlidir.

Dördüncü hata, skill'i çok uzun ve genel yazmaktır. Skill, ajanın zaten bildiği genel bilgileri tekrar etmemelidir. Gerçek değer; yerel prosedür, kalite standardı, hata durumu ve örnek çıktı formatındadır.

Beşinci hata, test etmeden kullanıma almaktır. MCP server ve skill birlikte çalıştığında beklenmeyen davranışlar çıkabilir. Normal senaryo, başarısız tool çağrısı, kötü niyetli input, eksik auth, rate limit ve yanlış tetiklenen skill gibi durumları test etmek gerekir.

Hangi MCP Server'ları Kurmaya Değer?

Yeni başlayan biri için önerdiğim sıra şu:

Documentation MCP: Context7 veya benzeri dokümantasyon server'ları. Risk düşüktür, faydası hızlı görülür.
Filesystem MCP: Sadece belirli proje klasörüyle sınırlı olacak şekilde.
Git/GitHub MCP: Önce read-only veya sınırlı issue/PR okuma yetkisiyle.
Browser/fetch MCP: Web içeriği çekmek için, ama prompt injection riskini bilerek.
Database MCP: Sadece read-only ve mümkünse staging/analytics verisiyle.
Özel API MCP: Kurum içi servisler için, auth ve audit tasarımıyla.

Bu sıranın mantığı risk-fayda dengesidir. Dokümantasyon server'ı genelde düşük risklidir. Filesystem biraz daha risklidir. GitHub write yetkileri daha risklidir. Database ve özel API'ler ise en dikkatli tasarlanması gereken alanlardır.

Hangi Skill'leri Yazmaya Değer?

Skill yazmaya değer işler genellikle tekrar eder ve kalite standardı ister.

Örneğin:

Blog yazma ve yayınlama workflow'u.
Kod review formatı.
UI tasarım kontrol listesi.
SEO/GEO optimizasyon süreci.
PDF/Excel işleme standardı.
Güvenlik inceleme prosedürü.
Deployment checklist'i.
Müşteri destek cevap tonu.
Akademik özet çıkarma formatı.
Veri analizi rapor şablonu.

Bir skill yazmadan önce kendinize şu soruyu sorun: "Bu işi ajana ikinci kez yaptırırken aynı talimatları tekrar yazmak zorunda kalıyor muyum?" Cevap evetse skill iyi adaydır.

Çok Kısa Bir Kurulum Senaryosu

Diyelim amacınız şu: "AI ajanım bu repo'da blog yazısı hazırlasın, kaynakları araştırsın, kapak görseli oluştursun ve Sanity formatına çevirsin."

Minimum yapı şöyle olur:

config.toml:

blog-publisher/SKILL.md:

Bu kurulumda MCP server veri ve dosya erişimini sağlar. Skill yayın akışını standartlaştırır. Upload script gerçek Sanity işlemini yapar. Böylece ajan sadece "blog yazan model" değil, sitenin yayın sistemine uyumlu çalışan bir üretim asistanı olur.

Ne Zaman MCP Kullanmamalısınız?

MCP her derde deva değildir. Eğer modelin sadece metin üretmesi gerekiyorsa MCP gereksiz olabilir. Eğer tek ihtiyaç sabit bir talimat ise skill yeterlidir. Eğer entegrasyon çok basit ve sadece sizin uygulamanız içinde kullanılacaksa doğrudan function calling veya küçük bir API wrapper daha pratik olabilir.

MCP özellikle şu durumlarda değerlidir:

Birden fazla AI client aynı entegrasyonu kullanacaksa.
Tool discovery ve standart protokol istiyorsanız.
Dış sistem erişimini AI ajanlarına modüler sunmak istiyorsanız.
Ekip içinde ortak server katalogları kurmak istiyorsanız.
Agent framework değişse bile entegrasyonu taşımak istiyorsanız.

MCP kullanmamak daha doğru olabilir:

Tek seferlik küçük script yazıyorsanız.
Tool yüzeyi çok tehlikeli ve güvenlik modeli hazır değilse.
API zaten uygulamanızın içinde basit bir fonksiyon olarak çağrılıyorsa.
Kullanıcı onayı, audit ve auth mekanizması kuramayacaksanız.

Ne Zaman Skill Kullanmamalısınız?

Skill de her şeye çözüm değildir. Eğer talimat bir cümleyle verilebiliyorsa ve tekrar etmeyecekse skill yazmak gereksizdir. Eğer süreç sürekli değişiyorsa ve daha oturmadıysa önce birkaç kez manuel çalışıp pattern'i görmek daha iyi olabilir. Eğer skill çok genel olacaksa değer üretmez.

Kötü skill örneği:

Bu skill neredeyse hiçbir şey katmaz. Çünkü model zaten yardımsever olmaya çalışır. İyi skill, genel temenni değil, görev bilgisi taşır.

Gelecek: Agent Engineering Bir Entegrasyon Disiplini Oluyor

MCP server'lar ve skill'ler bize daha büyük bir dönüşümü gösteriyor. AI geliştirme yalnızca prompt yazmak olmaktan çıkıyor. Artık mesele; bağlam yönetimi, tool güvenliği, izin modeli, kaynak seçimi, workflow paketleme, gözlemlenebilirlik ve tekrar edilebilir kalite standardı.

Bu yüzden "agent engineering" ifadesi giderek daha anlamlı hâle geliyor.

Gelecekte iyi AI sistemleri muhtemelen şöyle kurulacak:

Her ekip kendi domain skill'lerini yazacak.
Kurumlar onaylı MCP server katalogları tutacak.
Tool izinleri merkezi politikalara bağlanacak.
Skill ve MCP değişiklikleri code review gibi incelenecek.
Güvenlik ekipleri tool poisoning ve prompt injection testlerini standartlaştıracak.
Ajanlar sadece güçlü modellerle değil, iyi tasarlanmış context ve workflow ile değerlendirilecek.

Bu tablo biraz karmaşık görünebilir ama yazılım tarihine çok yabancı değil. Nasıl API, SDK, plugin, package manager ve CI/CD zamanla standartlaştıysa; AI ajanları tarafında da MCP, skill, AGENTS.md ve benzeri yapılar standart iş akışlarına dönüşüyor.

Sonuç

MCP server'lar ve agent skill'ler aynı sorunun iki farklı tarafını çözer: AI ajanını gerçek işe nasıl bağlarız? MCP server, ajana dış sistemlerle konuşma yeteneği verir. Skill, ajana belirli bir işi doğru şekilde yapma yöntemi verir. Biri araçtır, diğeri çalışma alışkanlığıdır. Biri kapı açar, diğeri o kapıdan geçince ne yapılacağını söyler.

Bu ayrımı doğru kurarsanız ajanlarınız daha güvenilir, daha tekrar edilebilir ve daha üretken olur. Her şeyi tek bir dev prompt'a yığmak yerine bilgiyi katmanlara ayırırsınız. Genel proje kuralları AGENTS.md içinde durur. Göreve özel prosedür skill olur. Dış sistem erişimi MCP server ile sağlanır. Model ise bu parçaları kullanarak plan yapar ve çıktı üretir.

Başlamak için büyük bir platform kurmanıza gerek yok. Bir düşük riskli MCP server seçin, örneğin dokümantasyon veya sınırlı dosya sistemi. Sonra sürekli tekrar ettiğiniz bir iş için küçük bir skill yazın. İkisini birlikte deneyin. Nerede hata yaptığını gözleyin. Tool listesini daraltın. Skill açıklamasını iyileştirin. Yazma işlemlerini onaya bağlayın. Bu küçük döngü, büyük ve güvenilir agent sistemlerinin temelidir.

MCP ve skill konusunu öğrenmek bugün biraz erken görünebilir.

Ama AI araçları sohbet kutusundan gerçek iş akışlarına taşındıkça bu kavramlar daha da merkezi olacak. Çünkü geleceğin güçlü AI sistemleri sadece zeki modellerden oluşmayacak. Doğru araçlara, doğru sınırlara, doğru prosedürlere ve doğru bağlama sahip ajanlardan oluşacak.

Kaynaklar ve Notlar

Model Context Protocol resmi dokümantasyonu: https://modelcontextprotocol.io/docs/getting-started/intro
MCP 2025-06-18 spesifikasyonu: https://modelcontextprotocol.io/specification/2025-06-18
MCP security best practices: https://modelcontextprotocol.io/specification/2025-06-18/basic/security_best_practices
modelcontextprotocol/servers GitHub deposu: https://github.com/modelcontextprotocol/servers
OpenAI API MCP and Connectors dokümantasyonu: https://developers.openai.com/api/docs/guides/tools-connectors-mcp
OpenAI Codex MCP dokümantasyonu: https://developers.openai.com/codex/mcp
OpenAI Codex Skills dokümantasyonu: https://developers.openai.com/codex/skills
OpenAI Skills Catalog GitHub deposu: https://github.com/openai/skills
Agent Skills açık standardı: https://agentskills.io/
Agent Skills specification: https://agentskills.io/specification
GitHub blog, VS Code prompt injection güvenliği: https://github.blog/security/vulnerability-research/safeguarding-vs-code-against-prompt-injections/
Invariant Labs mcp-scan güvenlik aracı: https://github.com/invariantlabs-ai/mcp-scan
Microsoft mcp-for-beginners güvenlik bölümü: https://github.com/microsoft/mcp-for-beginners

Bu rehberde dış kaynaklardan uzun alıntı kullanılmadı. MCP için "USB-C portu" benzetmesi resmi MCP dokümantasyonunda geçen kısa bir ifadeye dayanır; geri kalan teknik açıklamalar kaynakların özetlenmesi, karşılaştırılması ve pratik kullanıma uyarlanmasıyla hazırlanmıştır.