Ürün ekiplerinin müşterilerden duyduğu soru artık hep aynı: "Bunu Copilot'tan, Claude'dan ya da ChatGPT'den kullanabilir miyim?" Pratik cevap bir production MCP sunucusu, yani ürününüzün özenle seçilmiş bir bölümünü AI agent'lara açan bir Model Context Protocol endpoint'i. Zamanlama da uygun: 2026-07-28 tarihli MCP spesifikasyonu protokol çekirdeğini stateless hale getirdi ve yetkilendirmeyi sıkılaştırdı. Bugün başlayan bir ekip, ileride migration yapmak yerine doğrudan kararlı sürümün üzerine inşa edebilir. Bu rehberde adımları, her adımdaki trade-off'larla birlikte anlatıyoruz. Temel kural şu: küçük başla, stateless kur, kimlik doğrulamayı ilk günden koy.
2026-07-28 MCP spesifikasyonu neyi değiştirdi?
MCP projesinin sürüm duyurusuna göre bu revizyon stateless bir protokol çekirdeği, Multi Round-Trip Requests, header tabanlı routing, cache'lenebilir liste sonuçları, yetkilendirme sıkılaştırmaları, resmi bir extension çerçevesi ve güncellenmiş Tier 1 SDK'lar getiriyor. 28 Temmuz'daki nihai sürüm duyurusu, dört Tier 1 SDK'nın (TypeScript, Python, Go ve C#) yeni revizyonu desteklediğini ve SDK'ların ayda yaklaşık yarım milyar kez indirildiğini ekliyor. Mimariyi doğrudan etkileyen üç değişiklik var:
- Handshake ve session header yok. Google'ın geliştirici blogunun açıkladığı gibi initialize/initialized el sıkışması ve
Mcp-Session-Idheader'ı tamamen kaldırıldı. Protokol sürümü, istemci bilgisi ve yetenekler artık her istekte_metaalanında taşınıyor; her istek kendi başına anlamlı. - Sade yatay ölçekleme. Release candidate yazısına göre herhangi bir istek herhangi bir instance'a düşebiliyor. Protokol katmanında sticky routing ya da paylaşılan session store'a artık gerek yok.
- Yaşam döngüsü olan extension'lar. MCP Apps, sunucuların host tarafından sandbox'lı bir iframe içinde render edilen etkileşimli HTML arayüzler sunmasını sağlıyor. Tasks ise deneysel bir çekirdek özellikten extension'a taşındı. Her özellik artık Active → Deprecated → Removed döngüsünü izliyor ve deprecation ile en erken kaldırma arasında en az on iki ay bulunuyor. Bu, planlama için öngörülebilir bir pencere demek.
Planlamayı etkileyen iki değişiklik daha var. Roots, Sampling ve Logging deprecated oldu ama en az on iki ay çalışmaya devam edecek; eski HTTP+SSE transport'u için de bir yıllık geçiş süresi tanındı. Bunların üzerine yeni bir şey kurmayın. Yetkilendirme tarafında ise spesifikasyon Dynamic Client Registration'ı deprecated ilan ediyor: Yeni uygulamalar bunun yerine Client ID Metadata Documents kullanmalı.
1. Adım: Tüm API'nizi değil, 5–10 tool seçin
Her endpoint için otomatik bir tool üretmek cazip gelir. Yapmayın. Her tool, kontrol etmediğiniz bir modelle yapılmış bir sözleşme ve yeni bir saldırı yüzeyi; iyi tanımlanmış bir düzine tool da otomatik üretilmiş yüz tool'dan çok daha doğru kullanılır. İyi bir ilk katalog şöyle olur:
- Ağırlıkla okuma. Arama, sorgulama, özetleme. Agent'lar hızla işe yarar hale gelir, hatalar ucuz kalır.
- Sonuca göre şekillenmiş. İki iç çağrıyı birleştiren tek bir
get_order_statustool'u, modelin doğru sırayla zincirlemesi gereken üç düşük seviyeli tool'dan iyidir. - Dar girdili. Mümkün olan her yerde serbest metin filtreleri yerine enum'lar ve ID'ler.
- Tenant ya da kullanıcı ID'si parametre olmasın. Bunları sunucuda access token'dan türetin; böylece kafası karışmış ya da manipüle edilmiş bir agent başka bir müşterinin verisini isteyemez.
- v1'de geri alınamaz yazma yok. Yazma gerekiyorsa, kullanıcının uygulamanızda onaylayacağı bir taslak oluşturun.
Kod yazmadan önce kataloğu, her tool için tek bir scope ile yazıya dökün:
# v1 tool kataloğu: ağırlıkla okuma, her tool'a tek scope
- name: search_orders
scope: orders.read
returns: paginated order summaries
- name: get_order_status
scope: orders.read
combines: orders API + shipping API
- name: create_draft_invoice
scope: invoices.draft
note: draft only, user confirms in the app
2. Adım: Production MCP sunucusunu nasıl kuracağınızı seçin
Çoğu zaman sıfırdan MCP sunucusu yazmanız gerekmez. REST API'niz zaten Azure API Management arkasındaysa, yerleşik AI gateway seçtiğiniz API operasyonlarını MCP tool'u olarak dışarı açabilir. Özel sunucu yazmayı yalnızca gateway'in karşılayamadığı ihtiyaçlar için saklayın.
| API Management ile açmak | Özel sunucu (TypeScript SDK v2) | |
|---|---|---|
| Efor | Mevcut API üzerinde konfigürasyon | Yeni kod ve yeni deployment |
| MCP özellikleri | Yalnızca tool; resource ve prompt yok | Tool, resource ve prompt |
| Tool yapısı | Her tool bir API operasyonu | Birden fazla API çağrısını tek tool'da birleştirebilir |
| Hosting | Mevcut API Management instance'ınız | Örneğin Flex Consumption üzerinde Azure Functions |
Bilmeniz gereken trade-off'lar:
- API Management zaten işlettiğiniz gateway'i yeniden kullanır, ancak Microsoft dokümantasyonuna göre şu an yalnızca tool destekliyor. Dikkat edilmesi gereken bir nokta: MCP sunucu policy'lerinde
context.Response.Bodydeğişkenine erişmeyin. Bu, response buffering'i tetikliyor ve MCP'nin ihtiyaç duyduğu streaming davranışını bozuyor. - Azure Functions, resmi SDK'larla yazılmış sunucuları barındırabiliyor; bu özellik şu an public preview aşamasında. Preview, streamable-http transport kullanan stateless sunucuları destekliyor ve uygulamanın Flex Consumption planında çalışması gerekiyor. Gerçekten sunucu tarafında state tutmanız gerekiyorsa Microsoft, Functions MCP extension'ı öneriyor.
- Azure API Center, hem API Management üzerinden açılan hem de başka yerde barındırılan MCP sunucuları için private registry görevi görebiliyor. Böylece diğer ekipler mevcut sunucuları kolayca keşfeder.
Bir uyarı: Bu yazının yazıldığı tarihte Microsoft dokümantasyonu, iki Azure seçeneğinin 2026-07-28 wire revizyonunu sunup sunmadığını ya da proxy'leyip proxy'lemediğini açıkça belirtmiyor. API Management, gateway arkasına aldığı mevcut MCP sunucuları için yalnızca 2025-06-18 veya sonraki bir sürüme uyma şartı koyuyor. Karar vermeden önce güncel desteği kontrol edin; her iki protokol neslini de hesaba katmanın (4. Adım) bir nedeni de bu.
3. Adım: Tool'ları açık handle'larla stateless tasarlayın
Session'lar protokolden kalkınca, birden fazla adımdan oluşan iş akışlarının state'i başka bir yerde tutulmalı. Release candidate yazısındaki cevap, HTTP API'lerin hep kullandığı yöntem: Bir tool açık bir kimlik üretir (basket_id, browser_id gibi) ve model sonraki çağrılarda bunu sıradan bir argüman olarak geri gönderir.
{
"jsonrpc": "2.0",
"id": 7,
"method": "tools/call",
"params": {
"name": "add_line_item",
"arguments": {
"basket_id": "bsk_8f2c",
"sku": "PLAN-PRO",
"quantity": 1
}
}
}
Pratik kurallar:
- Handle'ın arkasındaki state'i sunucu belleğinde değil, normal veri deponuzda tutun.
- Her çağrıda, kimliği doğrulanmış kullanıcının o handle'ın gerçekten sahibi olduğunu kontrol edin. Handle bir işaretçidir, kimlik bilgisi değil.
- Handle'lara süre sınırı koyun ve mümkün olduğunca yazma tool'larını idempotent yapın; agent'lar isteği tekrar dener.
Sunucunun Flex Consumption gibi stateless ve yatay ölçeklenen bir ortamda çalışabilmesini sağlayan şey tam olarak bu tasarım.
4. Adım: Eski istemcileri dışarıda bırakmadan 2026-07-28'i hedefleyin
TypeScript SDK'nın ana branch'i v2 (@modelcontextprotocol/server ve @modelcontextprotocol/client); 2026-07-28 spesifikasyonunu uygulayan kararlı sürüm hattı bu. v1.x paketi (@modelcontextprotocol/sdk) ise v2'nin 2026-07-27'deki yayınından sonra en az altı ay boyunca bug fix ve güvenlik güncellemesi almaya devam ediyor.
npm install @modelcontextprotocol/server
Mevcut bir v1 sunucusunu taşımak için Node.js 20 veya üstü gerekiyor; SDK bir codemod da sunuyor. Codemod'u paketin kök dizininde çalıştırın, ardından otomatik dönüştüremediği kısımları elden geçirin:
node --version # 20 veya üstü olmalı
npx @modelcontextprotocol/codemod@latest v1-to-v2 .
SDK'nın migration rehberinden iki detay önemli:
- Yeni wire formatı opt-in. v2 ile oluşturulan bir sunucu, siz 2026-07-28'i açıkça etkinleştirmedikçe 2025 dönemi protokolüyle konuşmaya devam ediyor. Sadece paketi güncellemek wire'da hiçbir şeyi değiştirmez; yeni revizyonu bilinçli olarak açın ve test edin.
- Cache varsayılanları temkinli. 2026-07-28 sunulurken SDK liste cache alanlarını her zaman gönderiyor ve varsayılan olarak
ttlMs: 0ilecacheScope: 'private'kullanıyor. Bir listenin tüm kullanıcılar için aynı olduğundan ve nadiren değiştiğinden emin olana kadar bu varsayılanlara dokunmayın.
İşin rahatlatıcı kısmı birlikte çalışabilirlik. Diğer SDK'lar farklı davranıyor: SDK beta duyurusuna göre Go SDK'da da 2026-07-28'i sunmak bilinçli bir tercih; Python v2 sunucusu iki revizyonu tek endpoint'ten yanıtlıyor, C# preview'ın HTTP transport'u ise varsayılan olarak yeni stateless modda çalışıyor. TypeScript tarafında SDK'nın migration rehberine göre createMcpHandler aynı endpoint'ten 2026-07-28'i ve varsayılan olarak 2025 dönemi istekleri de servis ediyor; versionNegotiation: { mode: 'auto' } ile ayarlanmış bir v2 istemcisi de yalnızca 2025'i destekleyen bir sunucuya ulaştığında 2025 initialize handshake'ine geri dönüyor. Önerimiz: v2 üzerine kurun, yeni revizyonu bilinçli olarak açın, agent host'ları yetişene kadar bir geçiş döneminde eski istemcileri de kabul edin ve v1.x'ten çıkışı destek süresi bitmeden planlayın.
5. Adım: Güvenliği ilk günden kurun
Microsoft'un Azure Functions ekibi, bir MCP sunucusunu production'a taşımanın önündeki en büyük engelin hâlâ auth olduğunu açıkça söylüyor. Bu, konuyu ertelemek için değil, ilk iş olarak ele almak için bir neden.
Kimlik doğrulama. Microsoft Entra ID ile OAuth kullanın. Microsoft'un aka.ms/remote-mcp reposundaki örneklerin tamamı, kimlik sağlayıcı olarak Entra ID ile yerleşik MCP auth'u varsayılan olarak açıyor; makul bir başlangıç noktası. Yeni spesifikasyon akışı da sıkılaştırıyor: İstemciler authorization yanıtlarındaki iss parametresini doğrulamak zorunda (RFC 9207). RFC 8707 resource indicator'ları sayesinde istemciler bir token'ın hangi MCP sunucusu için olduğunu açıkça belirtiyor ve bu da confused deputy sorununu çözüyor. Siz de kendi tarafınızda, sunucunuz için verilmemiş token'ları reddedin ve istemcilerin authorization sunucunuzu bulabilmesi için OAuth 2.0 Protected Resource Metadata (RFC 9728) yayımlayın. Entra ID dışında bir kimlik sağlayıcı kullanıyorsanız, Client ID Metadata Documents desteği olduğunu varsaymayın, kontrol edin.
Token'ı web uygulamanızın kullandığı aynı kullanıcı, tenant ve rol kontrollerine bağlayın: agent, adına çalıştığı kişiden daha geniş yetkiye asla sahip olmamalı.
Token passthrough yok. İstemcinin size gönderdiği token'ı asla bir upstream API'ye iletmeyin. İç API'leri sunucunun kendi kimlik bilgileriyle, her tool'un tam olarak ihtiyaç duyduğu kapsamla çağırın; böylece orders.read hiçbir zaman faturalara erişim açmaz.
İnsan onayı. Spesifikasyon, host'ların herhangi bir tool'u çağırmadan önce kullanıcıdan açık onay almasını şart koşuyor. Silme, iade ya da gönderim gibi geri alınamaz işlemler için kendi katmanınızı ekleyin: Önce bir önizleme döndürün, işlemi ancak ayrı bir onay çağrısıyla gerçekleştirin.
Girdi doğrulama. NSA'in Mayıs 2026'da yayımladığı MCP güvenlik rehberi, zayıf girdi doğrulamayı ve yetersiz loglamayı MCP kurulumlarındaki yaygın açıklar arasında gösteriyor. Her tool'a katı bir JSON Schema verin ve kontrolleri sunucu tarafında tekrarlayın; modelin mantıklı değerler gönderdiğini asla varsaymayın.
Güvenilmeyen açıklamalar. Spesifikasyona göre tool açıklamaları, güvenilir bir sunucudan gelmedikçe güvenilmez kabul edilmeli. Üçüncü taraf tool'ları topluyorsanız açıklamalarını olduğu gibi aktarmayın.
Loglama. Her tool çağrısını parametreleri ve ilgili kimliklerle birlikte loglayın ve bu telemetriyi mevcut SIEM sisteminize aktarın. Log şemasını ilk olaydan sonra değil, lansmandan önce netleştirin. Örnek bir kayıt:
{
"ts": "2026-10-14T09:12:03Z",
"tool": "get_order_status",
"client": "partner-agent",
"subject": "user-7f3a",
"scopes": ["orders.read"],
"arguments": { "order_id": "ORD-1042" },
"result_sha256": "9c1e...",
"latency_ms": 184
}
6. Adım: Sunucuyu herhangi bir public API gibi işletin
MCP sunucusu, yeni bir istemci tipine sahip, internete açık bir API'dir. Ona da aynı disiplini uygulayın: düzenli patch takvimi, bağımlılık takibi ve versiyonlanmış değişiklikler. Lansmandan sonra:
- Kademeli yayın. Önce iç kullanıcılar, sonra birkaç tasarım ortağı müşteri, ardından herkese açık sürüm.
- Tool bazında metrikler. Her tool için çağrı hacmi, hata oranı ve gecikme. Hiçbir agent'ın çağırmadığı tool'lar kaldırılmaya adaydır; sık hata genellikle kafa karıştırıcı bir açıklamaya ya da şemaya işaret eder.
- Gateway'de rate limit ve kota, böylece kontrolden çıkan tek bir agent diğer müşterilerin hizmetini bozamaz.
- Kendi deprecation politikanız. Spesifikasyonun modelini izleyin: duyurun, eski tool'u belirli bir süre çalışır tutun, sonra kaldırın.
- Bir spesifikasyon takvimi. Deprecated özelliklerin on iki aylık pencerelerini ve v1 SDK desteğinin bitişini takip edin; migration'lar hiçbir zaman acil duruma dönüşmesin.
Üzerinde çalıştığınız framework de takip edilmeli. Next.js, Eylül 2026 güvenlik sürümünde geliştirme sunucusunun (next dev) isteğin hangi siteden geldiğini doğrulamayan bir MCP endpoint'i açtığını duyurdu. Production deployment'lar bu endpoint'i sunmuyor; düzeltmeler v16.3.8 (Active LTS) ve v15.5.27 (Maintenance LTS) sürümlerinde yayımlandı. Çıkarılacak ders şu: MCP yüzeyleri stack'inize yalnızca sizin yazdığınız koddan değil, araçlardan da girebilir. Geliştirici makinelerini de güncel tutun.
Agent'ın hiç gerekmediği durumları da bilin. Microsoft'un Agent Framework dokümanı bunu açıkça söylüyor: Bir görevi bir fonksiyonla halledebiliyorsanız agent yerine onu kullanın. Gece çalışan bir mutabakat işi için LLM gerekmez; MCP, kullanıcılar açık uçlu sorular sormak ya da ürününüzü başka araçlarla birleştirmek istediğinde değer katar.
Son olarak keşfedilebilirliği düşünün. Sunucuyu Azure API Center'a kaydetmek iç ekiplerin onu bulmasını kolaylaştırır. Agent tarafında ise Microsoft'un Azure Functions ekibi, Functions'ta barındırılan MCP sunucularını Foundry Toolbox'ta göstermeyi planlıyor; Toolbox, Foundry agent'larının tool'ları tek bir endpoint üzerinden keşfedip kullanmasını sağlayan yeni bir özellik; kendi agent'larınız sunucuyu kullanacaksa takip etmeye değer.
Öne çıkanlar
- Ağırlıkla okumaya dayalı, sonuca göre şekillenmiş 5–10 tool ile başlayın; her birine en az yetkili tek bir scope verin.
- Tool'lar yeterliyse mevcut API'nizi API Management üzerinden açın; özel SDK v2 sunucusunu resource, prompt veya birleşik tool ihtiyacına saklayın.
- Stateless tasarlayın: açık handle'lar döndürün ve her çağrıda sahipliği doğrulayın.
- SDK v2 üzerine kurun, 2026-07-28'i bilinçli olarak açın ve geçiş döneminde eski istemcileri desteklemeye devam edin.
- Hosting kararından önce Azure'un yeni wire revizyonunu destekleyip desteklemediğini teyit edin.
- Entra tabanlı OAuth, Protected Resource Metadata, audience kontrolü, token passthrough yasağı, katı şemalar, geri alınamaz işlemler için insan onayı ve eksiksiz SIEM loglamasıyla yayına çıkın.
- Sunucuyu ve framework'ünü her public API gibi düzenli olarak patch'leyin.
- İş deterministik kodla çözülebiliyorsa agent kullanmayın.