MCP bağlı uygulama entegrasyonu standartları

MCP sunucusu, uygulamanızın işlevlerini (MCP araçları) Bağlı Uygulamalar Platformu'na bağlamak için çerçeveyi oluşturur. Hizmetinizin sonuçlarını daha güvenilir bir şekilde seçmesi, çağırması ve işlemesi için MCP yapılandırmanızın aşağıdaki standartlara tam olarak uyması gerekir.

Kılavuz ilkeler

Her işlev için işlevin özelliklerine değil, kullanıcı niyetine ve kullanım alanlarına odaklanın. Açıklama, modele aracınızın ne işe yaradığını ve hangi kullanım alanlarına yanıt verebileceğini anlatmanın birincil yoludur.

Sürüm oluşturma

Ölçeklenebilir ve sağlam MCP dağıtımlarını desteklemek için yola dayalı sürüm oluşturma kullanan yapılandırılmış bir URI mimarisi (ör. /v1, /v2) kullanın. Bunu yaptığınızda geriye dönük uyumluluğu koruyabilir ve yeni özellikleri kontrol edebilirsiniz. Bunu https://gemini.mcp.company.com/mcp/v1 gibi sağlayıcıya özel alt alan adlarıyla tamamlamak, ayrıntılı trafik yönetimine ve farklı yapay zeka modellerinin benzersiz bağlamına ve işleme davranışlarına göre uyarlanmış araç tanımlarının optimizasyonuna olanak tanır.

MCP protokolü sürüm uyumluluğu

Bağlı Uygulamalar Platformu, 2025-11-25 sürümüne kadar Model Context Protocol (MCP) spesifikasyonunu destekler. Daha yeni spesifikasyon sürümleri henüz desteklenmemektedir.

  • Geliştirici sorumluluğu: MCP sunucunuzun, initialize el sıkışma sırasında ve tüm araç ve şema tanımlarında Bağlı Uygulamalar Platformu (2025-11-25) tarafından desteklenen bir protokol sürümüne kesinlikle uymasını sağlamak sizin sorumluluğunuzdadır.
  • Platformun geriye dönük uyumluluğu: Bağlı Uygulamalar Platformu gelecekte daha yeni MCP spesifikasyon sürümlerini kullanmaya başladığında istemcimiz, daha önce desteklenen protokol sürümleriyle geriye dönük uyumluluğu koruyacak. Böylece mevcut üretim entegrasyonları kesintisiz şekilde çalışmaya devam edecek.
  • Yükseltmeleri yönetme: Yeni desteklenen bir MCP spesifikasyonunu kullanmaya veya şema değişiklikleri yapmaya hazır olduğunuzda, bu güncellemeleri yeni bir sürümlü URI yolunda (örneğin, /mcp/v2) gösterirken mevcut uç noktanızı (/mcp/v1) etkin trafik için koruyun.

Uygulama sürümleri arasında MCP şemalarında değişiklik yapılmasına izin verilir. Bu özellikten yararlanmanızı ve yeni özelliklerin sorunsuz bir şekilde kullanıma sunulmasını desteklemek için MCP uç noktalarını sürümlendirmenizi veya yalnızca geriye dönük uyumlu değişiklikleri kullanmanızı öneririz.

Aktarım protokolü spesifikasyonu

Bağlı Uygulamalar Platformu, yalnızca Model Bağlam Protokolü spesifikasyonunun 2025-03-26 ve sonraki sürümlerinde Streamable HTTP aktarımını destekler. 2024-11-05 spesifikasyonunda açıklanan SSE aktarımı ile eski HTTP'yi desteklemez.

  • Tek HTTP uç noktası. Connected Console'da sağlanan MCP uç noktası (örneğin, https://api.example.com/mcp), geçerli Google ürünlerinin tüm JSON-RPC isteklerini (initialize, tools/list, tools/call) standart HTTP POST üzerinden gönderdiği tek URL'dir.
  • Akış yapılabilir HTTP içinde SSE akışı. Eski çoklu uç nokta SSE aktarımı desteklenmez ancak text/event-stream gibi Server-Sent Events, Streamable HTTP içinde desteklenir. Geçerli Google ürünlerinden gelen giden istekler Accept: application/json, text/event-stream içerir. Bu, sunucunuzun standart bir application/json yükü döndürebileceği veya doğrudan HTTP POST yanıt gövdesinde Content-Type: text/event-stream kullanarak artımlı yanıtlar yayınlayabileceği anlamına gelir.
  • GET akışı ve 405 Yöntemine İzin Verilmiyor. İstemciler, sunucudan istemciye bildirimler için uç noktada isteğe bağlı bir GET akışı deneyebilir. Sunucunuz durum bilgisi içermiyorsa veya yalnızca istek-yanıt tabanlıysa HTTP 405 Method Not Allowed döndürme işlemi, geçerli Google ürününün istemci proxy'si tarafından açıkça desteklenir ve sorunsuz bir şekilde gerçekleştirilir.

Sunucu talimatları

Bağlı Uygulamalar Platformu, sunucu talimatlarını alacak şekilde optimize edilmiştir. Bu sayede, modelin davranışını başka yöntemlerle mümkün olmayan bir düzeyde kontrol edebilirsiniz.

Sunucu talimatlarını uygulayın.

Kullanım bağlamıyla birlikte "model ipucu" olarak değerlendirilir.

Modellere ipucu sağlama konusunda aşağıdaki yönergeleri uygulayın.

  • Talimatları, LLM'nin sunucunun genel amacını ve özelliklerini anlamasına yardımcı olacak genel bir"ipucu" veya kılavuz olarak yazın.
  • Özellikleri listelemek veya modelin sunucunun araçlarını ve kaynaklarını nasıl kullanması gerektiğini açıklamak yerine neler yapabileceğini açıklayın. Model "ne" sorusunu doğru anlarsa kullanıcı yolculuğuna göre "nasıl" sorusunu oldukça iyi belirleyebilir.
  • Bu metnin doğrudan modelin sistem istemine ekleneceğini varsayın. Açık, yönlendirici ve jeton açısından verimli olmalıdır.

Tamamlayıcı olun, kopyalamayın

Bu alanı, tüm araçlar için geçerli olan genel bağlam için kullanın ve her bir aracın açıklamasıyla ilgili gereksiz bilgilerden kaçının.

Sunucu talimatı örnekleri

Aşağıdaki örneklerde, sunucu talimatlarının doğru şekilde yazılmasıyla ilgili yapılması ve yapılmaması gerekenler gösterilmektedir.

Önerilen Önerilmez

Uzman bir GitHub deposu yöneticisi gibi davran. Bu sunucu; depo meta verilerine, sorun takibine ve PR iş akışlarına kapsamlı erişim sağlar. Proje sağlığını korumak, önceliklendirmeyi otomatikleştirmek ve kod standartlarını sağlamak için bu asistanı kullanabilirsiniz. Aksi belirtilmedikçe tüm işlemlerin kimliği doğrulanmış kuruluş bağlamında gerçekleştirildiğini varsayın. Deponun düzenli kalması için eski mesaj dizilerini veya bağlantısı kaldırılmış PR'leri belirlemeye öncelik verin.

Kısa, yönlendirici ve modeli tamamlayıcı nitelikte olmalıdır.

  • "Nasıl" yerine "ne" (proje durumu, önceliklendirme) sorusunu tanımlar
  • Tüm araçlar için geçerli olan kimlik doğrulama kapsamından bahseder

Bu sunucuda GitHub için araçlar var. Kullanıcı sorunları sorduğunda list_issues aracını kullanmalısınız. PR oluşturmak için create_pull_request kullanabilirsiniz. Kullanıcının kodunu yönetmesine yardımcı olmak için bu araçları dikkatli bir şekilde kullanın. Bir aracı çağırmadan önce her zaman depo adını kontrol edin. Kullanıcı özet isterse önce araçları çağırın, ardından çıkışı özetleyin.

  • araç adlarını yeniden listelemeyin,
  • Modele "nasıl" düşüneceğini söylemeyin. Bu, modelin doğru seçimi yapmak için kullanıcı bağlamını kullanan yerleşik akıl yürütme özelliğiyle çelişebilir.
  • sunucunun erişiminin niteliğini veya belirli kısıtlamalarını açıklamaz)

Araç kuralları

Aşağıdaki yönergelerde, uygulamanızdaki çeşitli işlevler veya araçlar için MCP sunucusu yapılandırmaları oluşturmayla ilgili en iyi uygulamalar açıklanmaktadır.

Araç adlandırma kuralları

Aracınızı adlandırırken aşağıdaki kurallara uyun:

Sezgisel, insanlar tarafından okunabilir adlar kullanın

Belirsiz adlar yerine, net ve sezgisel anlamları olan, kullanıcılar tarafından okunabilir adlar kullanın. Örneğin, get_user_information, userInfo ifadesinden daha anlaşılırdır.

Doğru büyük/küçük harf stilini kullanma

Araç işlevi adları ve uygulama tetikleyicileri için aşağıdaki büyük/küçük harf kurallarına uyun:

  • Araç işlevi muhafazası. MCP şemanızda tanımlanan araç işlevi adları için snake_case veya camelCase kullanın (ör. get_user_information veya publishDraft).
  • Uygulama tetikleyici tanıtıcı büyük/küçük harf kullanımı. Uygulama tetikleyicileri ve bahsetmeler (ör. @MyTwoWordApp) büyük/küçük harfe duyarlı değildir. Platform, kullanıcı girişlerini küçük harf (@mytwowordapp), PascalCase (@MyTwoWordApp) ve camelCase (@myTwoWordApp) olarak normalleştirir.
  • Görünen ad biçimlendirmesi. Kullanıcı arayüzü öğelerinde net bir görsel görüntü için PascalCase veya standart boşluklar kullanarak resmi uygulama başlığınızı kaydedin.
  • Yazım hatası işleme. Büyük/küçük harf varyasyonları otomatik olarak işlenirken karakter yazım hataları (ör. @mytwowrodapp), doğrudan dize eşleştirme yerine yedek niyet tanımaya dayanır. Geliştiriciler, dokümanlarda herkese açık kullanıcı adının doğru yazılmasını teşvik etmelidir.

Açık fiil-isim adlandırması kullanın

verb_noun adlandırmasında net olun ve belirsizlikten kaçının. Örneğin, publish_draft, handle_content ifadesinden daha iyidir.

Araç ayrıntı düzeyi

Araç ayrıntı düzeyiyle ilgili aşağıdaki kurallara uyun.

Araçları atomik uç noktalar olarak ele alma

Araçları, araç içi koşullar veya ilgili gerekli parametrelerle birden fazla işlev içermeyen atomik uç noktalar olarak ele alın. Ayrıntılı araçlar, modelin adımları mantıklı bir şekilde zincirlemesine olanak tanıyarak halüsinasyonları azaltır.

Daha düz şemalar kullanma

Girişleri doğrulamak için derinlemesine iç içe yerleştirilmiş nesnelere veya karmaşık oneOf/anyOf şema mantığına ihtiyacınız varsa aracınız muhtemelen çok geniştir.

Önceden toplama ve yük koruma önlemlerine uyma

Küçük, kapsamlı yükler için verilerin önceden birleştirilmesi protokol tarafından kesin olarak zorunlu kılınmasa da büyük kayıt kümeleri, uzunlamasına geçmiş ve çok kaynaklı veri kümeleriyle çalışırken arka uçta önceden birleştirme yapılması pratikte kesinlikle gereklidir. Bağlı Uygulamalar Platformu; bağlam penceresi sınırları, yürütme gecikmesi ve model akıl yürütme adımlarıyla ilgili önlemler uygular. Bu kurallara uymak için aşağıdaki yönergeleri izleyin:

  • Arka uçta filtreleme ve özetleme yapın. Geçerli Google ürünlerine yanıt döndürmeden önce MCP sunucunuzdaki büyük veri akışlarını her zaman filtreleyin, önceden toplayın veya özetleyin.
  • Ham dökümlerden kaçının. Ham veritabanı satırlarını veya dizine eklenmemiş günlükleri hiçbir zaman aracın döndürdüğü yüke eklemeyin.

Dahili ve meta araçları hariç tutma

Sunucunuzun tools/list yanıtında yalnızca modele yönelik özellikleri gösterin:

  • Yardımcı araçları filtreleme: Model tarafından çağrılması amaçlanmayan tüm dahili, yönetimsel veya meta araçları (ör. sunucu durumu kontrolleri, dahili kurulum rutinleri veya geliştirici yardımcıları) çıkarın.
  • Bağlam penceresi verimliliği: Gereksiz araçları hariç tutmak, MCP şemanızı kısa tutar, bağlam penceresi jeton tüketimini azaltır ve model araç yönlendirme karışıklığını önler. Onlarca araç veya derinlemesine iç içe yerleştirilmiş "mega araç" şemaları sunan MCP sunucuları, düzeltmeler için inceleme sırasında işaretlenir.

Araç ayrıntı düzeyiyle ilgili yapılması ve yapılmaması gerekenler

Aşağıdaki örneklerde, araç adlandırma ve ayrıntı düzeyi kullanımıyla ilgili yapılması ve yapılmaması gerekenler gösterilmektedir.

Önerilen Önerilmez

Açık adlara ve parametrelere sahip ayrıntılı araçlar

Her aracın giriş şeması katıdır. LLM, kullanıcı oluşturmak istiyorsa bir e-posta adresi sağlamalıdır. Silmek istiyorsa bir kimlik sağlamalıdır. Tahmin yürütmeye gerek yok.

...
@mcp.tool()
def create_user(email: str, role: str = "viewer") -> str:
    """Register a new user. Returns the new User ID."""
    # Logic is purely creation
    return "user_123"

@mcp.tool()
def delete_user(user_id: str) -> str:
    """Permanently remove a user by their ID."""
    # Logic is purely deletion
    return f"User {user_id} deleted"

@mcp.tool()
def update_user_role(user_id: str, new_role: str) -> str:
    """Change an existing user's permission level."""
    return f"User {user_id} is now {new_role}"

    ...

Araç adı: manage_user

Açıklama: "Kullanıcı oluşturmak, güncellemek, silmek veya almak için bu aracı kullanın."

...
@mcp.tool()
def manage_user(
    action: Literal["create", "update", "delete", "get"],
    user_id: Optional[str] = None,
    email: Optional[str] = None,
    role: Optional[str] = "viewer"
) -> str:
    """
    Use this to manage users.
    WARNING: logic is hidden inside Python, not visible in the schema.
    """
    if action == "create":
        if not email: return "Error: Email required for creation" # Runtime error, not schema error
        return f"Created user {email}"
    elif action == "delete":
        if not user_id: return "Error: User ID required"
        return f"Deleted {user_id}"
    
    return "Action completed"
    """
    ...

Güvenlik için araç ek açıklamalarını beyan etme

Yürütme davranışını iletmek ve geçerli Google ürünlerinde yerleşik güvenlik kapılarını tetiklemek için araç tanımlarınızda protokol ek açıklamalarını yapılandırın:

  • Çalışma zamanı onay kapıları: Geçerli Google ürünleri, çalışma zamanı kullanıcı onayı istemlerini tetiklemek için anahtar işaretler olarak annotations.destructiveHint: true ve annotations.openWorldHint: true kullanır. Durum değiştiren, yazma veya yıkıcı eylemlerde destructiveHint: true değerini, açık dünya veya harici ortamlarla etkileşime giren araçlar için ise openWorldHint: true değerini tanımlayın. Böylece yüzey, yürütmeden önce kullanıcıdan yerel olarak onay ister.
  • Salt okunur sorgu ipucu: Arka uç durumunu değiştirmeden yalnızca veri getiren sorgu araçlarında readOnlyHint: true değerini ayarlayın.
  • Açık ek açıklama varsayılanları: Model Context Protocol spesifikasyonuna göre, readOnlyHint parametresinin atlanması, istemcilerin güvenlik için varsayılan olarak readOnlyHint: false ve destructiveHint: true parametrelerini varsaymasına neden olur. Tüm araçlarda ek açıklamaları açıkça beyan etmek, model yönlendirmenin tahmin edilebilir olmasını ve yürütme güvenliğinin sağlanmasını sağlar.

Araç açıklamaları

Açıklama, modelin aracınızın mevcut sorunu çözüp çözemeyeceğine karar vermek için sahip olduğu tek bağlamdır. Açıklama yazarken aşağıdaki kurallara uyun:

Yorum değil, talimat yazın

Araç açıklamalarını kod yorumları olarak değil, talimatlar olarak yazın. Kod yorumları genellikle pasiftir. Büyük dil modelleri, talimatlara iyi yanıt verir.

"Nasıl" sorusunu yanıtlayın

İyi bir açıklama, "Bir aracım var" ile "Bu aracı bir sohbete nasıl bağlayacağımı biliyorum" arasındaki boşluğu doldurur.

"Neden" sorusunu yanıtlayın

Bu aracı benzerlerinden ayırt edin. Örneğin, "Bu aracı kuruluş içi kullanıcılar, customer_update aracını ise kuruluş dışı kullanıcılar için kullanın".

Modele, bağımsız değişkenleri nerede bulacağını söyleyin (ör. "order_search aracından").

Biçimi belirtme

Birimleri (metre veya fit) ve biçimleri (ISO tarihleri, semantik sürümler) belirtin.

Modelin takdir yetkisini kullanmasını önleme

Modele "en iyi kararını" kullanması talimatını vermeyin veya isteğe bağlı, rehberlik edilmeyen eylemler önermeyin.

Araç açıklaması örnekleri

Aşağıdaki örneklerde, araç açıklamaları yazarken yapılması ve yapılmaması gerekenler gösterilmektedir.

Önerilen Önerilmez

Veri kaynağı

"Kullanıcının e-posta adresini günceller. search_users aracından döndürülen UUID "id" değerini kesinlikle kullanmalıdır. Kullanıcı kimliklerini tahmin etmeyin."

(Bir aracın çıkışını bu aracın girişine açıkça bağlar.)

"Kullanıcının e-posta adresini günceller."

(Model, 12345 gibi bir kimlik tahmin edebilir.)

Biçim ve kısıtlama

"Toplantı planla. "date" (tarih) ISO 8601 biçiminde (YYYY-AA-GG) olmalıdır. Kullanıcı 'yarın' veya başka bir göreceli referans kullanırsa tarihi mevcut bağlama göre hesapla."

"Belirtilen tarih için toplantı planla."

(İnsanlar için doğru görünür (ör. "yarın") ancak şema doğrulamasından geçemez ("2025-10-12" gerekir))

Çıktı beklentileri

"Sunucu günlüklerini alır. Ham metnin son 50 satırını döndürür. Analiz için daha küçük zaman pencereleri isteyerek jeton sınırlarına takılmayın."

"Sunucu günlüklerini al."

(Model, özet bekleyen bir aracı çağırabilir, ham 5 MB JSON dökümü alır ve kötü bir kullanıcı deneyimine neden olabilir.)

 
@mcp.tool()
def update_campaign_status(campaign_id: str, status: str) -> str:
    """
    Promotes or pauses an advertising campaign.
    
    CRITICAL USAGE RULES:
    1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'.
    2. 'status': Must be exactly one of: ['active', 'paused', 'archived'].
    
    Returns: A confirmation string with the new status and timestamp.
    """
    # Logic...

    ...

Bu açıklama, mini bir kılavuz görevi görür. Kaynak (kimliğin nereden alınacağı), Kısıtlamalar (geçerli enum'lar) ve İşlem'i işler.

 
@mcp.tool()
def update_campaign_status(id: str, status: str) -> str:
    """
    Updates the campaign status in the database.
    """
    # Logic...

Bu, tüm işi yapmak için değişken adlarını kullanır. Modelin "status" için geçerli değerleri tahmin etmesi gerekir.

Araç parametreleri

Aracın kendisinin yanı sıra parametreleri de açıklayarak netleştirin.

Açık türler

Güçlü ve spesifik türler (string, integer, boolean, array) kullanın.

Sabit değer kümeleri için enum'ları kullanma

Bir parametre yalnızca sabit bir değer kümesini (ör. daylight, cool, warm) kabul ediyorsa bunları bir enum dizisinde listeleyin. Bu sayede doğruluk oranı önemli ölçüde artar.

Gerekli parametreleri açıkça belirtin.

İşlevin çalışması için hangi parametrelerin zorunlu olduğunu açıkça tanımlayın.

Anlamsal şema eşleştirmeyi uygulama

Uygulamanızı entegre ederken araç parametrelerinizle geliştirdiğiniz sektör arasında semantik şema eşleşmesi gerekebilir. İlk katılım sürecinde beklenen dikey şemayı (JSON şeması) alırsınız.

Araç parametreleri örnekleri

Aşağıdaki örneklerde, araç parametrelerini işleme konusunda yapılması ve yapılmaması gerekenler gösterilmektedir.

Önerilen Önerilmez

Bağımsız değişken biçimleri ve birimleri

radius: "Metre cinsinden yarıçap. 0'dan büyük bir kayan değer olmalıdır."

(birim halüsinasyonunu önler)

radius: "Dairenin yarıçapı."

Kimlik biçimleri ve bağlam

user_id: "Veritabanı UUID'si (örneğin, 550e8400-e29b...). Bu alanda e-posta adresleri kullanmayın."

Not: En iyi uygulama olarak, tüm sayısal kimlik alanları dize değerleri olarak değerlendirilmelidir. Özellikle kimliğiniz 10'dan fazla basamaklıysa dahili sistemler tarafından kesilme (32 bitlik bir kapsayıcıya zorlanma) ve bu sürümün gelecekteki araç çağrılarında model tarafından kullanılma riski vardır.

(tür hatalarını önler)

user_id: "Kullanıcının kimliği."

Geri dönüş değeri beklentileri

"Kaydı günceller ve yeni zaman damgasını içeren güncellenmiş JSON nesnesini döndürür."

(Modele, değişikliği doğrulamak için "güncelleme"den hemen sonra bir "get" aracı çağırması gerekmediğini bildirir.)

"Kaydı günceller."

 

@mcp.tool()
def search_logs(query: str, limit: int = 10) -> str:
    """
    Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth').
    
    Args:
        query: A Lucene-formatted search string.
        limit: Max results to return. capped at 50.
    
    Returns:
        A formatted string of log entries with timestamps.
    """
    ...
  
@mcp.tool()
def search_logs(query: str, limit: int = 10) -> str:
    """Searches the logs."""
    ...

LLM, "sorgu"nun hangi söz dizimini desteklediğini (SQL? Normal ifade mi? Düz metin?) Maksimum "sınırın" ne olduğunu bilmez.

Yanıtlar ve hata işleme

Yanıt, bir sonraki istemdir temel ilkesi uyarınca araç, temel yürütme işleminin sonucunu bir veri yükü döndürerek bildirir. Bu veri yükü daha sonra doğrudan LLM'nin bağlam penceresine yapıştırılır. Sonucun başarılı veya başarısız olması, bir sonraki adımda ne olacağını belirler:

  • Başarılı olursa: Modelin bir sonraki adımına karar vermek için ne olduğunu bilmesi gerekir. Bu nedenle, dönüş değerine ihtiyacı vardır.
  • Başarısız olursa: Modelin neden başarısız olduğunu ve nasıl çözüleceğini bilmesi gerekir. Kilitlenme (500 hatası) sohbeti durdurur. Açıklayıcı bir hata mesajı, modelin kendi kendini düzeltmesine olanak tanır.

Aracınızın temel mantığı başarılı veya başarısız olsa da modelin kolayca ayrıştırabilmesi için dönüş değeri yükünüzü biçimlendirmeniz gerekir. Yanıt yükünüzü paketlerken aşağıdaki en iyi uygulamaları izleyin.

JSON kullanma

Yapılandırılmış verileri TextContent'te biçimlendirin (geçici kısıtlama). structuredContent henüz Bağlı Uygulamalar Platformu'nda desteklenmediğinden verilerinizi manuel olarak serileştirin. Basit bir liste döndürse bile json.dumps().

Yanıta URL'leri dahil etme

Döndürülen URL'ler nispeten kısa olmalı ve çok fazla parametre içermemelidir. Jeton sayısından tasarruf etmek ve halüsinasyon riskini azaltmak için URL kısaltma hizmetlerini kullanmanız önerilir.

Kendi kendini açıklayan halüsinasyon önleyici yükler

Ham kodları veya dahili kimlikleri her zaman okunabilir görünen adlar, açık ölçü birimleri ve referans aralıklarıyla eşleştirin. Modeli bağlamı tahmin etmeye zorlayan sıkıştırılmış sözlük anahtarları veya eşlenmemiş sayısal kodlar döndürmeyin.

Hataların etkili bir şekilde yönetilmesini sağlayın.

Modelin neyin yanlış gittiğini anlayabilmesi ve kullanıcıyı bilgilendirebilmesi için net ve anlamlı hata mesajları döndürün. MCP hata işleme bölümüne bakın.

try/except kullanma

Araç mantığını try/except bloklarına sarmalayın ve dizeye dönüştürülmüş hatalar döndürün.

İşlem yapılabilir hatalar sağlama

Hata mesajında bir sonraki adımı önerin (ör. "Önce X aracını kullanmayı deneyin").

İşlemleri onayla

Yan etki araçları (oluşturma/güncelleme/silme) için boş dize döndürmeyin.

Yanıtlar ve hata işleme örnekleri

Aşağıdaki örneklerde, yanıtlar ve hata işleme ile ilgili yapılması ve yapılmaması gerekenler gösterilmektedir.

Önerilen Önerilmez

Açık serileştirme


...
import json

@mcp.tool()
def query_metrics(metric_id: str) -> str:
    result = {"id": metric_id, "value": 42, "unit": "ms"}
    # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON
    return json.dumps(result, indent=2)


...
@mcp.tool()
def query_metrics(metric_id: str) -> str:
    result = {"id": metric_id, "value": 42, "unit": "ms"}
    # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON
    return str(result)

Yakala ve bilgilendir


...
@mcp.tool()
def get_user_details(user_id: str) -> str:
    try:
        user = db.get_user(user_id)
        if not user:
             # GOOD: Informative error returned as content
            return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'."
        return json.dumps(user)
    except Exception as e:
        return f"Error: Database connection failed ({str(e)}). Please try again later."

(Araç teknik olarak "başarılı" olur (bir dize döndürür) ancak dize, hata ayrıntılarını içerir. Model bunu okur, "Bu kimlik mevcut değil" der ve kullanıcıdan doğru kimliği isteyebilir.) 


...
@mcp.tool()
def get_user_details(user_id: str) -> str:
    # BAD: Unhandled exception if ID not found
    user = db.get_user(user_id)
    return json.dumps(user)

(get_user başarısız olursa sunucu 500 hatası verir. LLM, genel bir yürütme hatası alır ve bunun nedenini bilmez (Kimlik yanlış mıydı? Veritabanı çalışmıyor mu? İzin reddedildi mi?). Büyük olasılıkla aynı hatalı girişi tekrar dener.)

Boş Yanıtlar

...
@mcp.tool()
def post_story(story_content: str) -> str:
    service_name = "story_service"
    api_client.post("/stories", json={"content": story_content})
    # GOOD: Explicit confirmation of state change.
    return f"Service '{service_name}' successfully posted content. Status is now 'posted'."


...
@mcp.tool()
def post_story(storyContent: str):
    subprocess.post(["postsrv", "story", storyContent])
    # BAD: Returns null/empty string. Model is confused.

LLM'ler genellikle boş yanıtlar nedeniyle kafa karışıklığı yaşar. "Araç başarısız oldu" şeklinde halüsinasyon görebilir veya çağrıyı tekrarlayabilir.

Kendi kendini açıklayan halüsinasyon önleyici yük

Ham kodları veya dahili kimlikleri her zaman kolayca okunabilen görünen adlar, açık ölçü birimleri ve normal referans aralıklarıyla eşleştirin.

{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}

(Bu sayede model, birimleri veya referans eşikleri tahmin etmek zorunda kalmadan değerin tam olarak ne anlama geldiğini öğrenir.)

Ham kimlikler, özel sıkıştırma veya eşlenmemiş kodlar

Etiketsiz ham dahili kimlikler, özel sözlük kısaltmaları veya sayısal kodlar döndürme.

{"code": "2345-7", "v": 105}

(Modeli 105'in neyi ifade ettiğini tahmin etmeye zorlar. Bu da uydurma birimlere, bağlam eksikliğine veya yanlış açıklamalara yol açar.)

MCP hata işleme

Hataları düzgün bir şekilde ele almak çok önemlidir.

  • Kurtarılabilir hatalar (ör. geçersiz kullanıcı kimliği veya eksik isteğe bağlı parametre) için araç yanıtında açıklayıcı hata ayrıntıları içeren normal bir metin dizesi döndürün. Bu sayede model, geri bildirimi inceleyebilir, neyin yanlış gittiğini anlayabilir ve kendi kendini düzeltebilir veya kullanıcıdan açıklama isteyebilir.
  • Uç hatalar (ör. sıklık sınırlaması, kimlik doğrulama veya izin hataları ya da arka uç sunucu kesintileri) için platformun hatayı sistematik olarak işleyebilmesi amacıyla uygun hata kodunu içeren bir McpError oluşturun.

Örnek hata yanıtı gövdesi (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message, MCP'nin ErrorData alanının JSON dökümünü içerir. Bağlı Uygulamalar Platformu, doğru code ve model tarafından görülebilen message değerini döndürerek hata mesajını okuyabilir ve kullanıcıya doğal dilde faydalı bir açıklama iletebilir. Örneğin, "Maalesef bu kimliğe sahip mekanı bulamadım. Adı kontrol edebilir misiniz?"

MCP, istemcilerin JSON-RPC 2.0 spesifikasyonunu kullanarak MCP sunucularına bağlanmasına olanak tanır. JSON-RPC'de, geçersiz istek ve ayrıştırma hataları gibi sık karşılaşılan hatalar için önceden tanımlanmış belirli hatalar gönderilir. Bu kılavuzda, MCP sunucularının özel hataları nasıl geri gönderebileceği açıklanmaktadır.

Durum
Kodu		 Mesaj Kullanım Açıkça
return
kullanmanız gerekiyor mu?
Kullanıcı/Müşteri Hataları
-32300 USER_RATE_LIMITED Kullanıcı, maksimum kullanım sınırına ulaştı. EVET
-32301 MISSING_REQUIRED_INFORMATION Giriş isteğinde gerekli tüm bilgiler yok EVET
-32302 USER_PERMISSION_DENIED Kullanıcı, aracın kullanılmasına izin vermedi. Örneğin, kullanıcının kurumsal hesabı olması, yaş kısıtlaması, yerel ayar vb. veya aracın kurumsal aboneliğinin olmaması gerekir. EVET
Uygulama Hataları/İş Mantığı Hataları
-32400 RUNTIME_ERROR Sunucu kodu yürütme işlemi hata verdi EVET
-32401 NULL_POINTER_EXCEPTION Boş bir işaretçiyi/nesneyi çalıştırma girişimi EVET
-32402 OUT_OF_MEMORY Sunucu kodunda bir nesneye tahsis edilecek yeterli bellek yok. EVET
Altyapı Hataları
-32500 DEADLINE_EXCEEDED İstek, izin verilen süreyi aşıyor. Aşırı yüklenmiş sunucu, ağ sorunları vb. birçok nedenden dolayı ortaya çıkabilir. EVET
-32501 RESOURCE_EXHAUSTED Sunucuda yetersiz bellek, disk alanı, iş parçacığı, CPU süresi vb. kalmadı. EVET
-32502 SERVICE_UNAVAILABLE Bağımlı hizmet (ör.başka bir mikro hizmet, veritabanı, önbellek vb.) kullanılamıyor. EVET
JSON-RPC hataları (Bu hatalar, MCP aktarımının bir parçasıdır.)
-32700 PARSE_ERROR Sunucu, isteği ayrıştıramadı. HAYIR
-32600 INVALID_REQUEST Hatalı biçimlendirilmiş istemci isteği HAYIR
-32601 METHOD_NOT_FOUND Geçersiz MCP aracı adı HAYIR
-32602 INVALID_PARAMS İstek parametreleri geçersiz. Eksik parametreler veya eşleşmeyen parametre türleri var. HAYIR
-32603 INTERNAL_ERROR Varsayılan yanıt HAYIR

Aşağıda, resmi Python SDK'sını (mcp) kullanarak sunucunuzda nasıl MCP hatası oluşturabileceğinizle ilgili bir örnek verilmiştir. ErrorData yükü içeren bir McpError oluşturun. SDK, bu yükü otomatik olarak gerekli JSON-RPC hata biçimine dönüştürür ve hata durumunu doldurur.

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

Araç Bağlamı

Geçerli Google ürünleri, sinyalleri MCP sunucularına iletmek için bir Tool Context API'yi destekler. Bu API, hassas bilgi gerektiren geçerli kullanım alanlarında (ör. yerelleştirme gerektiren araçların yerel ayarı gibi temel araç tanımının parçası olmayan meta veriler) kullanılır. Tool Context API yalnızca Connected Console üzerinden kullanılabilir.

Connected Console'da uygulamanızla current_user_location_fine gibi bir sinyal kaydettiğinizde geçerli Google ürünleri, MCP tools/call isteklerini istenen verileri sağlayan ek bir _meta girişiyle genişletir. Desteklenen sinyal grubu şunlardır:

  • current_user_location_fine (Yalnızca Gemini, izin verilen sektörler için)
  • user_locale
  • current_user_location_coarse
{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

Bu verileri incelemek için:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

Kullanıcı deneyiminin oluşturulması

MCP uygulamaları

Geçerli Google ürünleri, özel kullanıcı arayüzleri oluşturulmasına olanak tanımak için seçili kullanıcı yolculuklarında MCP Uygulamaları entegrasyonlarını destekler. Genel entegrasyon talimatları için spesifikasyonu uygulayın.

Geçerli Google ürünlerinde MCP Apps entegrasyonu aşağıdaki uyarılarla birlikte sunulur.

Kayıt sırasında kaynak kullanımı

Geçerli Google ürünleri, araç listesi ve araç açıklamalarına benzer şekilde, araç besleme sırasında kullanıcı arayüzü kaynaklarını getirir. Bu, kaynak güncellemelerinin (ör. JavaScript'teki değişiklikler) otomatik olarak alınmayacağı ve aracın yeniden beslenmesi gerektiği anlamına gelir.

Tek bir kullanıcı arayüzü kaynağının boyutu 15 MB'ı, sunucunuzdaki toplam kullanıcı arayüzü kaynaklarının boyutu ise 100 MB'ı aşmamalıdır.

Kullanıcı arayüzü kaynakları, desteklenen MIME türlerinden birini kullanmalıdır: text/html, text/javascript, text/css veya text/html;profile=mcp-app. Standart olmayan veya platforma özgü MIME türleri, önizlemeye aktarılırken doğrulanamaz.

CSP Yönergeleri

Geçerli Google ürünleri, İGP [1], [2] içeren resmi MCP Uygulamaları spesifikasyonuna uyar ve İGP yönergelerini ihlal eden tüm istekleri engeller.

Geçerli Google ürünleri, kullanılıyorsa CSP'ye blob: ve data: eklenmesini de gerektirir. Bunlar varsayılan olarak eklenmez. Bunları CSP'ye ekleyip eklememek geliştiricinin tercihidir.

Script-src bir istisnadır

İzin verdiğimiz tek yönergeler şunlardır: unsafe-inline (varsayılan olarak eklenir), wasm-unsafe-eval ve data: (resource_domains içinde yer alıyorsa). iframe harici komut dosyaları yüklüyorsa bu sorun, JS'yi HTML'ye paketleyerek veya alt kaynak bütünlüğü (SRI) karması kullanılarak çözülebilir.

  • 1. seçenek: JS'yi HTML'ye satır içi olarak ekleme/paketleme (en basit yöntem)

    • Paket JS Kodu:

      • Kullanıcı arayüzü kaynağı için döndürülen HTML yükünde component-init.js içeriğini doğrudan <script> etiketlerinin içine satır içi olarak ekleyin:

        <script>
// Paste component-init.js content directly here
</script>

    • Uzak <script src> Etiketlerini Kaldır

      • HTML belgesinden <script src="https://api.mycompany.com/..."> referanslarını silin.

    • Yeniden Alma/Güncelleme Aracı

  • 2. seçenek: Alt Kaynak Bütünlüğü (SRI) karma değerini kullanma:

    Komut dosyasının harici olarak https://api.company.com/... adresinde barındırılması gerekiyorsa bu seçeneği kullanın.

    • Komut dosyasının SHA-256 karmasını hesaplama
      • component-init.js için base64 SHA-256 karma değeri oluşturun.
    • resourceDomains özelliğine karma ekleyin (integrity özelliğiyle eşleşmesi için sha256- önekini içermelidir)
    • HTML <script> etiketini güncelleme
      • HTML widget'ındaki komut dosyası etiketine integrity ve crossorigin özelliklerini ekleyin.
    • CDN/sunucuda CORS başlığını doğrulama
      • Tarayıcının SRI doğrulaması için yanıt gövdesini okuyabilmesi amacıyla api.company.com, component-init.js öğesini Access-Control-Allow-Origin: * ile sunmalıdır (veya scf.usercontent.goog öğesine izin vermelidir).
    • Yeniden Alma/Güncelleme Aracı

MCP aracı açıklaması için güvenlik kuralları

Açıklama, modelin aracın özelliklerini anlamak için sahip olduğu tek bağlamdır. Bu nedenle, istenmeyen davranışları önlemek için doğru ve güvenli bir şekilde yazılmalıdır. Araç açıklamalarınızı hazırlarken aşağıdaki kurallara uyun.

  • İşlevleri açıklayın ancak davranışları dikte etmeyin. Açıklama, aracın ne yaptığını doğru bir şekilde açıklamalı, modele sonraki işlemleri gerçekleştirmesi için komut vermemelidir.
  • Kapsamı ve gereksinimleri tanımlayın. Aracın birincil amacını, kullanımına yönelik belirli koşulları (Ne zaman) ve gerekli tüm girişleri (parametreler/argümanlar) açıkça belirtin.
  • Doğruluğu sağlama Açıklama, aracın temel kodunu doğru bir şekilde temsil etmelidir. Yazma veya silme işlemi gerçekleştiren bir aracın salt okunur olduğunu iddia etmeyin.

Güvenlik riskleri ve bunlardan kaçınma yöntemleri

Risk alanı Önerilen Bu uygulamadan kesinlikle kaçının

İstem enjeksiyonu

Aracın amacını ve işlevini net bir şekilde belirtmek için nesnel ve açıklayıcı bir dil kullanın.

Model davranışını geçersiz kılmak veya sistem akışlarını değiştirmek için emir kipiyle komutlar kullanma (ör. "... demen GEREKİR", "Koştuktan sonra..."). MUST veya CRITICAL gibi zorunluluk belirten terimler yalnızca yapılandırılmış parametre kısıtlamaları veya kullanım kuralları tanımlanırken kullanılabilir.

Araç açıklama metni için standart, düz biçimlendirme kullanın.

Dikkat çekici biçimlendirme (ör. aşırı büyük harf kullanımı ve VERY IMPORTANT: veya **CRITICAL** gibi etiketler) kullanma

Yalnızca aracın işlevine ve beklenen davranışına odaklanın.

Rol yapma talimatları veya önceki talimatları yok sayma komutları ekleme

Araç gölgeleme ve ele geçirme

Açıklamanın spesifik olduğundan ve aracın gerçek, ilgili özellikleriyle sınırlı olduğundan emin olun.

Araç açıklamasını aşırı geniş veya belirsiz tutmayın ya da tek bir aracın birçok alakasız işlevi yerine getirdiğini iddia etmeyin.

Benzersiz, açıklayıcı ve mantıklı bir araç adı seçin.

Güvenilir bir aracın adının küçük bir varyasyonu olan bir araç adı veya genel bir ad (ör. do_everything_tool, assistant_tool) kullanma

Açıklamanızda diğer uygulamaların veya harici platform araçlarının adını belirtmeyin.

Diğer araçlara açıkça referans verin veya diğer araçların ne zaman ya da nasıl kullanılacağına dair yeni kurallar oluşturun.

Modelin planlayıcısının, kullanıcı bağlamına göre en uygun aracı seçmesine izin verin.

Rekabet karşıtı ifadeler veya modele, benzer araçlar yerine sizin aracınızı tercih etmesini söyleyen her türlü SEO istemi ekleme

Tetikleyici manipülasyonu

Açıklama, genel sohbet geçmişi ifadelerine atıfta bulunmuyor veya bunlara tepki vermiyor.

Yaygın ve zararsız kullanıcı ifadelerine (ör. "teşekkür ederim", "özetlemek gerekirse") dayalı olarak zararlı bir eylemi tetikleyen koşullu mantık oluşturma.

Parametrelerin kötüye kullanımı

Yalnızca aracın işlevi için gerekli parametreleri tanımlayın ve giriş verilerine özel adlar kullanın (ör. file_id, search_term).

İşlev parametrelerini, temsilcinin dahili durumunu yansıtan adlarla tanımlayın (ör. system_prompt, conversation_history, full_context).

Veri hırsızlığı

Tasarım aşamasında gizlilik: Şeffaf olmayan tanımlayıcılar ve ana makine tarafından yönetilen kimlik doğrulama.

Ham kimliği tanımlayabilecek bilgiler (PII) yerine hassas olmayan kimlikler kullanın. Tüm veri işleme işlemleri yetkili, güvenli sınırlar içinde olmalı ve herkese açık açıklamada harici olarak gönderildiği belirtilmemelidir. Araç yürütme, OAuth el sıkışması aracılığıyla izinleri sessizce devralır.

Tüm hassas bilgiler, geçerli Google ürünlerine gönderilmeden önce temizlenmelidir.

Kullanıcıdan kimliği tanımlayabilecek bilgiler (PII), koruma altındaki sağlık bilgileri (PHI) veya diğer kişisel ve/veya hassas bilgileri, kişisel ya da iş verilerini ya da tüzel kişileri, geçerli Google ürünlerinin hizmet şartlarını ihlal edecek şekilde talep etme.

Kullanıcı verilerinin (sorgu, konum, bağlam) yetkisiz üçüncü taraf URL'lerine, günlük kaydı hizmetlerine veya harici sistemlere gönderilmesinden bahsetme ya da bunu zorunlu kılma.

İşlevsel ve adlandırmayla ilgili en iyi uygulamalar

Aracınızın açıklamasını güvenli hale getirmenin yanı sıra modelin, aracı kafa karışıklığı yaşamadan güvenilir bir şekilde seçip çalıştırabilmesini de sağlamanız gerekir. Aşağıdaki işlevsel ve adlandırmayla ilgili en iyi uygulamalara uyun:

  • Parametre doğruluğu. Açıklamadaki tüm parametre adlarının ve türlerinin, aracın gerçek uygulamasıyla tam olarak eşleştiğinden emin olun.
  • Anlamlı adlandırma. Aracın adı, işlevi hakkında güçlü ve net bir ipucu vermelidir. "execute" gibi aşırı genel adlar kullanmaktan kaçının. Ad, daha geniş araç ekosistemiyle de tutarlı olmalıdır.

Ek: Altyapı ve ağ izin verilenler listesi

Barındırma altyapınız, API ağ geçidiniz veya güvenlik duvarınız gelen bağlantıları kaynak IP adresine göre kısıtlıyorsa aşağıdaki Google giden CIDR bloklarını izin verilenler listesine ekleyin:

  • 108.177.64.0/20
  • 142.250.88.0/22
  • 172.217.80.0/20
  • 192.178.20.0/22
  • 192.179.0.0/20
  • 74.125.232.0/24
  • 136.121.40.0/21

Ortamınızın, HTTPS bağlantı noktası 443 üzerinden bu IP aralıklarından gelen trafiğe izin verdiğinden emin olun. Böylece geçerli Google ürünleri, MCP başlatma, araç keşfi ve istek yürütme için uzak MCP sunucunuza erişebilir.