Azure Container Apps'te MCP sunucularında sorun giderme

Bu makale, Azure Container Apps'te MCP sunucularını dağıtırken ve kullanırken karşılaşabileceğiniz yaygın sorunları kapsar. Sorunlar kategoriye göre düzenlenir ve aksi belirtilmedikçe hem tek başına kapsayıcı uygulamaları hem de platform tarafından yönetilen dinamik oturumlar için geçerlidir.

Bağlantı ve giriş

Bağlantı sorunları MCP istemcilerinin sunucunuza ulaşmasını engeller. Bu sorunlar genellikle giriş yapılandırması, DNS veya ağ ilkeleriyle ilgilidir.

MCP istemcisi sunucuya ulaşamıyor

Belirtiler: VS Code, GitHub Copilot veya başka bir MCP istemcisinden bağlanırken bağlantı zaman aşımı veya DNS çözümleme hatası.

Nedenler ve çözümler:

Nedeni	Çözüm
Giriş olarak ayarlanmadı `external`	Doğrulamak için komutunu çalıştırın `az containerapp ingress show` . Genel erişim için `external: true` ayarlayın.
FQDN yanlış	Doğru ana bilgisayar adını almak için komutunu çalıştırın `az containerapp show --query properties.configuration.ingress.fqdn` .
TLS sertifika sorunu	Container Apps yönetilen TLS sağlar. Özel etki alanı kullanıyorsanız sertifikanın doğru şekilde bağlandığını doğrulayın.
İstemci bir güvenlik duvarının arkasında	giden HTTPS'ye (bağlantı noktası 443) izin verildiğinden `*.azurecontainerapps.io`emin olun.

Yanlış uç nokta yolu

Belirtiler: 404 Not Found MCP sunucusuna bağlanırken.

Doğru uç nokta yolu, MCP SDK'nıza ve yönlendirme yapılandırmanıza bağlıdır.

Çerçeve	Ortak uç nokta yolu	Notes
.NET (`MapMcp`)	`/mcp`	Yol, `MapMcp("/mcp")` içindeki güzergah ile eşleşir
Python (FastAPI'ye bağlı FastMCP)	`/mcp`	SDK uygulamasını FastAPI'ye `/` bağlayın; SDK `/mcp`
Python (FastMCP tek başına)	`/mcp`	FastMCP'i bağlamadan doğrudan çalıştırırken
Node.js (Express)	`/mcp`	Yol, Express yolu ile eşleşir
Java (Spring Boot SSE)	`/mcp`	SSE taşıma; oluşturucuda `WebMvcSseServerTransportProvider` yol ayarlandı
Platform tarafından yönetilen oturumlar	`mcpServerEndpoint` değerinden	Azure Resource Manager (ARM) API'si tarafından sağlanan tam URL; oturum havuzu özelliklerinden alma

Python'da 404 hatalarının yaygın bir nedeni FastMCP uygulamasını FastAPI yönlendiricisine / yerine /mcp üzerinde bağlamaktır. SDK kendi /mcp alt yolunu eklediğinden, /mcp konumunda bağlamak bir /mcp/mcp uç noktası sağlar. /mcp adresine bağlayın, böylece nihai yol / olur.

Curl ile test ederek uç noktanın yanıt verdiğini doğrulayın:

curl -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"1","method":"initialize"}'

Tarayıcı tabanlı istemcilerde CORS hataları

Belirtiler: Access to fetch has been blocked by CORS policy tarayıcı konsolunda.

Uyarı

VS Code masaüstündeki GitHub Copilot tarayıcı CORS'lerini kullanmaz. Bu sorun yalnızca tarayıcı tabanlı MCP istemcilerini veya Web için VS Code'ı etkiler.

Çözüm: Kapsayıcı uygulamasında CORS'yi yapılandırın:

az containerapp ingress cors update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --allowed-origins "https://your-trusted-domain.com" \
    --allowed-methods "GET" "POST" "OPTIONS" \
    --allowed-headers "Content-Type" "Authorization" "Mcp-Session-Id"

Uyarı

Sorun giderme için geçici olarak ayarlayabilirsiniz --allowed-origins "*". Üretim dağıtımları için izin verilen kaynakları belirli güvenilen etki alanlarıyla kısıtlayın. Yönergeler için bkz. Container Apps'te MCP sunucularının güvenliğini sağlama.

Protokol ve aktarım

MCP istemcisi ile sunucu arasındaki JSON-RPC iletileri yanlış biçimlendirilmiş veya eşleşmeyen aktarımları kullandığında protokol hataları oluşur.

"Yöntem bulunamadı" yanıtı

Belirtiler: JSON-RPC yanıtı ile error.code: -32601.

Nedenler:

initialize öncesinde bir istek gönderiliyor. Her zaman önce gönder initialize .
Yanlış yazılmış yöntem adı. Kullanın tools/list ve tools/call (nokta gösterimiyle değil, eğik çizgiyle).
SSE yöntem adlarını HTTP aktarımıyla veya tam tersini kullanma.

Eksik veya yanlış biçimlendirilmiş JSON-RPC zarf

Belirtiler: 400 Bad Request veya Parse error (-32700).

Çözüm: Her isteğin gerekli JSON-RPC alanlarını içerdiğinden emin olun:

{
    "jsonrpc": "2.0",
    "id": "unique-request-id",
    "method": "tools/call",
    "params": { ... }
}

id bir string veya sayı olmalıdır. Alan jsonrpc tam olarak "2.0"olmalıdır.

Taşıma uyuşmazlığı

Belirtiler: SSE istemcisi 404 veya 405 hataları alıyor. HTTP istemcisi beklenmeyen text/event-stream içerik türü alıyor.

MCP birden çok taşımayı destekler. İstemcinizin ve sunucunuzun aynı aktarımı kullandığından emin olun.

Sunucu aktarımı	İstemci kullanmalı
Akışla aktarılabilir HTTP (`StreamableHTTPServerTransport`)	HTTP POST uç noktası
SSE (`SSEServerTransport`)	İletiler için SSE bağlantısı artı POST
Platform tarafından yönetilen (oturumlar)	Başlık ile `x-ms-apikey` HTTP POST

Çoğu modern MCP SDK'sı varsayılan olarak akışla aktarılabilir HTTP'dir. SSE kullanan bir sunucuya bağlanıyorsanız (eski örneklerde yaygın olarak bulunur), istemcinizi SSE moduna geçirin.

Uyarı

MCP Java SDK'sı henüz kararlı bir akışla aktarılabilir HTTP aktarımı sunmadığından Java öğreticisi SSE aktarımını (WebMvcSseServerTransportProvider) kullanır. VS Code'dan bağlanırken, SSE'yi seçin ve "type": "sse" öğesini .vscode/mcp.json içinde kullandığınızdan emin olun.

Dağıtım ve ölçeklendirme

Dağıtım sorunları kapsayıcınızın başlatılmasını veya doğru yanıt vermesini engeller. Bu sorunlar genellikle sistem durumu yoklamaları, bağlantı noktası yapılandırması veya ölçeklendirme ayarlarıyla ilgilidir.

Kapsayıcı sağlık kontrollerini geçemiyor

Belirtiler: Kapsayıcı tekrar tekrar yeniden başlatılır. Günlükler sağlık denetimi hatalarını gösteriyor.

Neden: Varsayılan başlangıç ve canlılık yoklamaları, kapsayıcının bağlantı noktasına HTTP GET istekleri gönderir. MCP uç noktaları genellikle yalnızca POST isteklerini kabul eder.

Çözüm: Uygulamanıza bir GET /health uç noktası ekleyin ve bu uç nokta 200 OK döndürsün. Ardından kapsayıcı uygulama yoklamalarınızı bu uç noktayı kullanacak şekilde yapılandırın. Sağlık denetimlerini MCP uç noktasına yönlendirmeyin.

Aşağıdaki örnek, bir yola işaret eden bir /health başlatma sondası ekler.

az containerapp update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --yaml probe-config.yaml

Prob probe-config.yaml yapılandırmasını içerir.

properties:
  template:
    containers:
      - name: mcp-server
        probes:
          - type: startup
            httpGet:
              path: /health
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          - type: liveness
            httpGet:
              path: /health
              port: 8080
            periodSeconds: 30

Bağlantı noktası uyuşmazlığı

Belirtiler: Kapsayıcı başlatılır ancak giriş döndürür 502 Bad Gateway.

Neden: Kapsayıcı, Container Apps giriş trafiğinin beklediği bağlantı noktasından farklı bir bağlantı noktasında dinler.

Çözüm: Bağlantı noktası yapılandırmasını doğrulayın:

# Check the target port
az containerapp ingress show \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --query targetPort

# Update if needed
az containerapp ingress update \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --target-port 8080

Uygulamanızdaki ortam değişkeninin PORT hedef bağlantı noktasıyla eşleştiğinden emin olun.

Soğuk başlatma gecikmesi

Belirtiler: İlk istek, işlem yapılmadığında 10-30 saniye sürer.

Neden: Container Apps varsayılan olarak sıfıra ölçeklendirilir. İlk istek soğuk bir başlangıç tetikler.

Çözümler:

Minimum replica sayısını 1 olarak ayarlayın: az containerapp update --name <APP_NAME> --resource-group <RESOURCE_GROUP> --min-replicas 1
Soğuk başlangıç süresine uyum sağlamak için sağlık denetimi zaman aşımını artırın.
MCP oturumları için platform kullanılabilirliği yönetir. Bu coolDownPeriodInSeconds ayar, havuz kullanılabilirliğini değil tek tek oturum ömrünü denetler.

Authentication

Kimlik doğrulama sorunları genellikle barındırma modeliniz için yanlış kimlik bilgisi türünü kullandığınızda oluşur. Aşağıdaki tabloda doğru kimlik doğrulama yaklaşımı özetlemektedir.

Barındırma modeli	Doğru üst bilgi	Yaygın hata
Bağımsız + yerleşik kimlik doğrulaması	`Authorization: Bearer <TOKEN>`	`x-ms-apikey`’ı kullanma
Dinamik oturumlar MCP	`x-ms-apikey: <KEY>`	`Authorization: Bearer`’ı kullanma

401 Yetkilendirilmemiş: tek başına uygulama kapsayıcısı

Belirtiler: 401 Unauthorized Yerleşik kimlik doğrulaması etkinleştirilmiş bir MCP sunucusuna bağlanırken verilen yanıt.

Kontrol listesi:

Taşıyıcı belirtecinin geçerli olduğunu doğrulayın: az account get-access-token --resource <APP_ID> --query accessToken
Authorization başlıkta belirtecin gönderildiğini doğrulayın.
Microsoft Entra uygulama kaydının audience istediğiniz kaynakla eşleşir olup olmadığını denetleyin.
--unauthenticated-client-action Ayarı doğrulayın. Return401 kimliği doğrulanmamış istekleri engeller; AllowAnonymous üzerinden geçmelerine izin verir.

Kimlik doğrulama hatası: dinamik oturumlar MCP

Belirtiler: Platform tarafından yönetilen MCP uç noktası çağrılırken kimlik doğrulama hatası. Hata bir HTTP 401 yanıtı olarak veya yanıt gövdesinde JSON-RPC hata iletisi olarak görünebilir. Hata türü, istek işlem hattında hatanın nerede oluştuğuna bağlıdır.

Denetim listesi:

API anahtarının x-ms-apikey üst bilgi üzerinden (değil Authorization) gönderildiğini doğrulayın.
Anahtarın fetchMCPServerCredentials'den geldiğini, farklı bir API'den olmadığını doğrulayın.
Anahtarı kısa süre önce yeniden oluşturdıysanız, eski anahtarın önbelleğinin süresinin dolması için beş dakika kadar bekleyin.
mcpServerSettings.isMCPServerEnabled öğesinin oturum havuzunda true olduğunu denetleyin.

Daha fazla bilgi için kimlik doğrulama kılavuzuna bakın.

Dinamik oturumlar

Bu bölümdeki sorunlar yalnızca dinamik oturumlarda platform tarafından yönetilen MCP sunucusu için geçerlidir. Tek başına kapsayıcı uygulaması sorunları için önceki bölümlere bakın.

Çevre Kimliği bulunamadı

Belirtiler: tools/call Yanıt, ortamın veya oturumun mevcut olmamasıyla ilgili bir hata içeriyor.

Nedenler:

Oturum süresi doldu (süre coolDownPeriodInSeconds aşıldı).
environmentId launchShell yanıtından doğru şekilde ayıklanmamış.
Farklı bir oturum havuzundan bir ortam kimliği kullanıyorsunuz.

Çözüm: Yeni bir ortam oluşturmak için yeniden arayın launchShell .

Oturum havuzunda MCP etkinleştirilmedi

Belirtiler: Oturum havuzu özelliklerinde mcpServerEndpoint yok.

Çözüm: MCP'nin etkinleştirildiğini doğrulayın:

az rest --method GET \
    --uri "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.App/sessionPools/<SESSION_POOL_NAME>" \
    --uri-parameters api-version=2025-02-02-preview \
    --query "properties.mcpServerSettings"

Eğer isMCPServerEnabledfalse ise veya alan yoksa, oturum havuzunu mcpServerSettings bloğu ile yeniden dağıtın.

Bölgesel kullanılabilirlik

Belirtiler: Dağıtım "bu bölgede kullanılamıyor" hatasıyla başarısız oluyor.

Neden: MCP ile dinamik oturumlar önizleme sırasında Azure bölgelerinin bir alt kümesinde kullanılabilir.

Çözüm: Desteklenen bölgelerin geçerli listesi için oturum belgelerine bakın.

Tanılama ve hata ayıklama

Destek isteği göndermeden önce tanılama bilgilerini toplamak için aşağıdaki teknikleri kullanın.

Sorunları tanılama ve çözme aracını kullanma

Azure portalı, kapsayıcı uygulamanız için yerleşik tanılama sağlar.

Azure portalınaoturum açın.
Container uygulamanıza gidin.
Gezinti çubuğunda Sorunları tanılama ve çözme'yi seçin.
Sorununuzla ilgili bir sorun giderme kategorisi seçin.

Kapsayıcı günlüklerini görüntüleme

Kapsayıcı uygulamanızdan günlükleri aktararak uygulama çıkışını ve hatalarını izleyin.

az containerapp logs show \
    --name <APP_NAME> \
    --resource-group <RESOURCE_GROUP> \
    --follow

MCP istemcilerini kullanmadan önce curl kullanarak test edin

GitHub Copilot veya diğer MCP istemcilerini yapılandırmadan önce curl kullanarak sunucunun doğru yanıt verdiğini doğrulayın:

# 1. Initialize
curl -sS -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"1","method":"initialize"}'

# 2. List tools
curl -sS -X POST "https://<APP_NAME>.azurecontainerapps.io/mcp" \
    -H "Content-Type: application/json" \
    -d '{"jsonrpc":"2.0","id":"2","method":"tools/list"}'

Her iki komut da geçerli JSON-RPC yanıtları döndürürse, sunucu çalışır ve sorun büyük olasılıkla istemci yapılandırmasındadır.

VS Code'da MCP günlüklerini inceleme

MCP istemciniz olarak GitHub Copilot kullanıyorsanız yerleşik MCP günlüklerini denetleyin:

Çıkış panelini açın (Çıkışı Görüntüle>).
Açılan listeden GitHub Copilot Sohbeti - MCP'yi seçin.
Bağlantı hataları, kimlik doğrulama hataları veya araç çağırma sorunlarını arayın.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-02-27

Aracılığıyla paylaş

Azure Container Apps'te MCP sunucularında sorun giderme

Bağlantı ve giriş

MCP istemcisi sunucuya ulaşamıyor

Yanlış uç nokta yolu

Tarayıcı tabanlı istemcilerde CORS hataları

Protokol ve aktarım

"Yöntem bulunamadı" yanıtı

Eksik veya yanlış biçimlendirilmiş JSON-RPC zarf

Taşıma uyuşmazlığı

Dağıtım ve ölçeklendirme

Kapsayıcı sağlık kontrollerini geçemiyor

Bağlantı noktası uyuşmazlığı

Soğuk başlatma gecikmesi

Authentication

401 Yetkilendirilmemiş: tek başına uygulama kapsayıcısı

Kimlik doğrulama hatası: dinamik oturumlar MCP

Dinamik oturumlar

Çevre Kimliği bulunamadı

Oturum havuzunda MCP etkinleştirilmedi

Bölgesel kullanılabilirlik

Tanılama ve hata ayıklama

Sorunları tanılama ve çözme aracını kullanma

Kapsayıcı günlüklerini görüntüleme

MCP istemcilerini kullanmadan önce curl kullanarak test edin

VS Code'da MCP günlüklerini inceleme

İlgili içerik

Geri Bildirim

Ek kaynaklar