एमसीपी से कनेक्ट किए गए ऐप्लिकेशन के इंटिग्रेशन के स्टैंडर्ड

एमसीपी सर्वर, आपके ऐप्लिकेशन के फ़ंक्शन (एमसीपी टूल) को Connected Apps Platform से कनेक्ट करने के लिए फ़्रेमवर्क सेट अप करता है. आपकी सेवा के नतीजों को ज़्यादा भरोसेमंद तरीके से चुनने, कॉल करने, और प्रोसेस करने के लिए, आपके एमसीपी कॉन्फ़िगरेशन को इन स्टैंडर्ड का सख्ती से पालन करना चाहिए.

मार्गदर्शन करने वाले सिद्धांत

हर फ़ंक्शन के लिए, उपयोगकर्ता के मकसद और इस्तेमाल के उदाहरणों पर फ़ोकस करें, न कि फ़ंक्शन की क्षमताओं पर. ब्यौरे की मदद से, मॉडल को यह बताया जाता है कि आपका टूल किस काम के लिए है और यह किन कामों में मदद कर सकता है.

वर्शन

एमसीपी को बड़े पैमाने पर और बेहतर तरीके से डिप्लॉय करने के लिए, स्ट्रक्चर्ड यूआरआई आर्किटेक्चर का इस्तेमाल करें. इसमें पाथ-आधारित वर्शनिंग का इस्तेमाल किया जाता है. उदाहरण के लिए, /v1, /v2. ऐसा करने से, आपको पुराने सिस्टम के साथ काम करने की सुविधा बनाए रखने और नई सुविधाओं को गेट करने में मदद मिलती है. इसे सेवा देने वाली कंपनी के हिसाब से सबडोमेन के साथ इस्तेमाल करने से, ट्रैफ़िक को बारीकी से मैनेज किया जा सकता है. जैसे, https://gemini.mcp.company.com/mcp/v1. साथ ही, अलग-अलग एआई मॉडल के यूनीक कॉन्टेक्स्ट और प्रोसेसिंग के तरीकों के हिसाब से, टूल की परिभाषाओं को ऑप्टिमाइज़ किया जा सकता है.

एमसीपी प्रोटोकॉल के वर्शन के साथ काम करने की सुविधा

Connected Apps Platform, मॉडल कॉन्टेक्स्ट प्रोटोकॉल (एमसीपी) के वर्शन 2025-11-25 तक की खास जानकारी के साथ काम करता है. फ़िलहाल, नई स्पेसिफ़िकेशन रिलीज़ का इस्तेमाल नहीं किया जा सकता.

  • डेवलपर की ज़िम्मेदारी: यह पक्का करना आपकी ज़िम्मेदारी है कि आपका एमसीपी सर्वर, कनेक्टेड ऐप्लिकेशन प्लैटफ़ॉर्म (2025-11-25) के साथ काम करने वाले प्रोटोकॉल वर्शन का पूरी तरह से पालन करे. ऐसा initialize हैंडशेक के दौरान और सभी टूल और स्कीमा की परिभाषाओं के लिए किया जाना चाहिए.
  • प्लैटफ़ॉर्म के पुराने सिस्टम के साथ काम करने की सुविधा: आने वाले समय में, Connected Apps Platform, एमसीपी स्पेसिफ़िकेशन के नए वर्शन अपनाएगा. हमारा क्लाइंट, पहले से काम करने वाले प्रोटोकॉल वर्शन के साथ काम करता रहेगा, ताकि मौजूदा प्रोडक्शन इंटिग्रेशन बिना किसी रुकावट के काम करते रहें.
  • अपग्रेड मैनेज करना: जब आप एमसीपी की नई सुविधा को अपनाने या स्कीमा में बदलाव करने के लिए तैयार हों, तो उन अपडेट को नए वर्शन वाले यूआरआई पाथ (उदाहरण के लिए, /mcp/v2) पर दिखाएं. साथ ही, चालू ट्रैफ़िक के लिए अपने मौजूदा एंडपॉइंट (/mcp/v1) को बनाए रखें.

ऐप्लिकेशन के अलग-अलग वर्शन के बीच, एमसीपी स्कीमा में बदलाव किए जा सकते हैं. हमारा सुझाव है कि आप इस सुविधा का फ़ायदा लें और एमसीपी एंडपॉइंट के वर्शन बनाएं, ताकि नई सुविधाओं को धीरे-धीरे रोल आउट किया जा सके. इसके अलावा, पुराने सिस्टम के साथ काम करने वाले बदलावों पर ही भरोसा करें.

ट्रांसपोर्ट प्रोटोकॉल की खास बातें

कनेक्ट किए गए ऐप्लिकेशन का प्लैटफ़ॉर्म, सिर्फ़ स्ट्रीम किए जा सकने वाले एचटीटीपी ट्रांसपोर्ट मॉडल कॉन्टेक्स्ट प्रोटोकॉल के 2025-03-26 और इसके बाद के वर्शन के साथ काम करता है. यह 5 नवंबर, 2024 की खास जानकारी में बताए गए एसएसई ट्रांसपोर्ट के साथ लेगसी एचटीटीपी के साथ काम नहीं करता.

  • सिंगल एचटीटीपी एंडपॉइंट. Connected Console में दिया गया एमसीपी एंडपॉइंट (उदाहरण के लिए, https://api.example.com/mcp) वह यूआरएल है जहां Google के लागू होने वाले प्रॉडक्ट, स्टैंडर्ड HTTP POST के ज़रिए सभी JSON-RPC अनुरोध (initialize, tools/list, tools/call) भेजते हैं.
  • स्ट्रीम किए जा सकने वाले एचटीटीपी में एसएसई स्ट्रीमिंग. लेगसी मल्टी-एंडपॉइंट एसएसई ट्रांसपोर्ट की सुविधा काम नहीं करती. हालांकि, स्ट्रीम किए जा सकने वाले एचटीटीपी में, सर्वर से भेजे गए इवेंट काम करते हैं. जैसे, text/event-stream. Google के लागू होने वाले प्रॉडक्ट से भेजे जाने वाले अनुरोधों में Accept: application/json, text/event-stream शामिल होता है. इसका मतलब है कि आपका सर्वर, स्टैंडर्ड application/json पेलोड दिखा सकता है या Content-Type: text/event-stream का इस्तेमाल करके, HTTP POST रिस्पॉन्स बॉडी में सीधे तौर पर इंक्रीमेंटल रिस्पॉन्स स्ट्रीम कर सकता है.
  • GET stream और 405 Method Not Allowed. क्लाइंट, सर्वर से क्लाइंट को मिलने वाली सूचनाओं के लिए, एंडपॉइंट पर वैकल्पिक GET स्ट्रीम का इस्तेमाल कर सकते हैं. अगर आपका सर्वर स्टेटलेस है या सिर्फ़ अनुरोध-जवाब वाला है, तो HTTP 405 Method Not Allowed को साफ़ तौर पर वापस करना, Google के लागू प्रॉडक्ट के क्लाइंट प्रॉक्सी के ज़रिए साफ़ तौर पर मैनेज किया जाता है.

सर्वर के लिए निर्देश

Connected Apps Platform को सर्वर से मिलने वाले निर्देशों को प्रोसेस करने के लिए ऑप्टिमाइज़ किया गया है. इससे मॉडल के व्यवहार को कुछ हद तक कंट्रोल किया जा सकता है. ऐसा अन्य तरीकों से नहीं किया जा सकता.

सर्वर से जुड़े निर्देशों का पालन करें.

इस्तेमाल के संदर्भ के साथ "मॉडल हिंट" के तौर पर इस्तेमाल करना

मॉडल को हिंट देने के लिए, इन दिशा-निर्देशों का पालन करें.

  • निर्देशों को हाई-लेवल "हिंट" या गाइड के तौर पर लिखें, ताकि एलएलएम को सर्वर के मकसद और क्षमताओं को समझने में मदद मिल सके.
  • यह बताएं कि टूल क्या कर सकता है. इसके बजाय, सुविधाओं की सूची न बनाएं या यह न बताएं कि मॉडल को सर्वर के टूल और संसाधनों का इस्तेमाल कैसे करना चाहिए. अगर मॉडल "क्या" को सही तरीके से समझता है, तो वह उपयोगकर्ता की गतिविधि के आधार पर "कैसे" को भी अच्छी तरह से तय कर सकता है.
  • यह मान लें कि यह टेक्स्ट, सीधे तौर पर मॉडल के सिस्टम प्रॉम्प्ट में जोड़ दिया जाएगा. इसे साफ़, निर्देश देने वाला, और टोकन-कुशल रखें.

कॉन्टेंट को बेहतर बनाएं, डुप्लीकेट न बनाएं

इस स्पेस का इस्तेमाल, ग्लोबल कॉन्टेक्स्ट के लिए करें. यह कॉन्टेक्स्ट सभी टूल पर लागू होता है. इससे हर टूल के ब्यौरे में दोहराव से बचा जा सकता है.

सर्वर के निर्देशों के उदाहरण

यहां दिए गए उदाहरणों में, सर्वर के निर्देशों को सही तरीके से लिखने के लिए, क्या करना चाहिए और क्या नहीं, इस बारे में बताया गया है.

सुझाव इसका सुझाव नहीं दिया जाता

मान लो कि तुम GitHub रिपॉज़िटरी के स्पेशलिस्ट मेंटेनर हो. यह सर्वर, रिपॉज़िटरी के मेटाडेटा, समस्या को ट्रैक करने, और पीआर वर्कफ़्लो का ऐक्सेस देता है. इसका इस्तेमाल करके, प्रोजेक्ट की परफ़ॉर्मेंस को बेहतर बनाएं, समस्याओं को अपने-आप प्राथमिकता के हिसाब से क्रम में लगाएं, और कोड के स्टैंडर्ड को पक्का करें. यह मान लें कि सभी कार्रवाइयां, पुष्टि किए गए संगठन के संदर्भ में की जाती हैं. हालांकि, ऐसा तब तक माना जाएगा, जब तक कि कोई और जानकारी न दी गई हो. रिपॉज़िटरी को व्यवस्थित रखने के लिए, पुराने थ्रेड या अनलिंक किए गए पीआर की पहचान करने को प्राथमिकता दें.

कम शब्दों में, निर्देश देने वाला, और मॉडल के लिए मददगार

  • "कैसे" के बजाय "क्या" (प्रोजेक्ट की परफ़ॉर्मेंस, प्राथमिकता तय करना) को तय करता है
  • पुष्टि करने के स्कोप के बारे में जानकारी दी गई है, जो सभी टूल पर लागू होता है

इस सर्वर में GitHub के लिए टूल मौजूद हैं. जब उपयोगकर्ता समस्याओं के बारे में पूछे, तब आपको list_issues टूल का इस्तेमाल करना चाहिए. पीआर बनाने के लिए, create_pull_request का इस्तेमाल किया जा सकता है. उपयोगकर्ता को उसका कोड मैनेज करने में मदद करने के लिए, इन टूल का इस्तेमाल सावधानी से करें. किसी टूल को कॉल करने से पहले, रिपॉज़िटरी का नाम हमेशा जांच लें. अगर उपयोगकर्ता किसी विषय की खास जानकारी मांगता है, तो पहले टूल को कॉल करें. इसके बाद, आउटपुट की खास जानकारी दें

  • टूल के नाम फिर से न डालें,
  • मॉडल को यह न बताएं कि उसे "कैसे" सोचना है. इससे मॉडल की पहले से मौजूद तर्क करने की क्षमता पर असर पड़ सकता है. यह क्षमता, उपयोगकर्ता के संदर्भ का इस्तेमाल करके सही विकल्प चुनने में मदद करती है.
  • सर्वर के ऐक्सेस या उसकी खास सीमाओं के बारे में नहीं बताया गया है)

टूल से जुड़े दिशा-निर्देश

यहां दिए गए दिशा-निर्देशों में, आपके ऐप्लिकेशन में मौजूद अलग-अलग फ़ंक्शन या टूल के लिए, एमसीपी सर्वर कॉन्फ़िगरेशन बनाने के सबसे सही तरीके बताए गए हैं.

टूल के नाम रखने के तरीके

अपने टूल का नाम रखने के लिए, इन दिशा-निर्देशों का पालन करें:

ऐसे नाम इस्तेमाल करें जो समझने और पढ़ने में आसान हों

ऐसे नाम इस्तेमाल करें जिन्हें कोई भी व्यक्ति आसानी से पढ़ सके और जिनका मतलब साफ़ तौर पर समझ आए. उदाहरण के लिए, get_user_information, userInfo से ज़्यादा आसान है.

केसिंग स्टाइल का सही इस्तेमाल करें

टूल फ़ंक्शन के नामों और ऐप्लिकेशन ट्रिगर के लिए, केसिंग के इन नियमों का पालन करें:

  • टूल फ़ंक्शन केसिंग. अपने एमसीपी स्कीमा में तय किए गए टूल फ़ंक्शन के नामों के लिए, snake_case या camelCase का इस्तेमाल करें. उदाहरण के लिए, get_user_information या publishDraft.
  • ऐप्लिकेशन ट्रिगर हैंडल केसिंग. ऐप्लिकेशन ट्रिगर और टैग (उदाहरण के लिए, @MyTwoWordApp) केस-इनसेंसिटिव होते हैं. यह प्लैटफ़ॉर्म, उपयोगकर्ता के इनपुट को लोअरकेस (@mytwowordapp), PascalCase (@MyTwoWordApp), और camelCase (@myTwoWordApp) में सामान्य बनाता है.
  • डिसप्ले नेम का फ़ॉर्मैट. अपने ऐप्लिकेशन का आधिकारिक टाइटल रजिस्टर करने के लिए, PascalCase या स्टैंडर्ड स्पेस का इस्तेमाल करें. इससे यूज़र इंटरफ़ेस (यूआई) एलिमेंट में टाइटल साफ़ तौर पर दिखेगा.
  • टाइपिंग की गलतियों को ठीक करना. केसिंग वैरिएशन अपने-आप मैनेज हो जाते हैं. हालांकि, वर्णों की टाइपिंग की गड़बड़ियां (उदाहरण के लिए, @mytwowrodapp) डायरेक्ट स्ट्रिंग मैचिंग के बजाय, फ़ॉलबैक इंटेंट की पहचान पर निर्भर करती हैं. डेवलपर को दस्तावेज़ों में हैंडल की सही स्पेलिंग लिखने के लिए बढ़ावा देना चाहिए.

नाम रखने के लिए, साफ़ तौर पर वर्ब-नाउन का इस्तेमाल करें

verb_noun का नाम सटीक रखें और ऐसी भाषा का इस्तेमाल न करें जिसका मतलब समझने में मुश्किल हो. उदाहरण के लिए, publish_draft, handle_content से बेहतर है.

टूल की जानकारी का लेवल

टूल की बारीकियों के बारे में जानने के लिए, यहां दिए गए दिशा-निर्देशों को देखें.

टूल को ऐटॉमिक एंडपॉइंट के तौर पर इस्तेमाल करना

टूल को ऐटॉमिक एंडपॉइंट के तौर पर इस्तेमाल करें. इनमें टूल के अंदर की शर्तें या ज़रूरी पैरामीटर के साथ कई फ़ंक्शन शामिल न हों. बारीकी से काम करने वाले टूल की मदद से, मॉडल को तार्किक तरीके से चरणों को जोड़ने में मदद मिलती है. इससे गलत जानकारी देने की संभावना कम हो जाती है.

फ़्लैटर स्कीमा का इस्तेमाल करना

अगर आपको इनपुट की पुष्टि करने के लिए, डीप नेस्टेड ऑब्जेक्ट या कॉम्प्लेक्स oneOf / anyOf स्कीमा लॉजिक की ज़रूरत है, तो हो सकता है कि आपका टूल बहुत बड़ा हो.

प्री-एग्रीगेशन और पेलोड से जुड़े दिशा-निर्देशों का पालन करें

हालांकि, छोटे और सीमित पेलोड के लिए, प्रोटोकॉल के तहत डेटा को पहले से इकट्ठा करना ज़रूरी नहीं है. हालांकि, बड़े रिकॉर्ड सेट, लंबे समय के इतिहास, और कई सोर्स वाले डेटासेट के साथ काम करते समय, बैकएंड पर डेटा को पहले से इकट्ठा करना ज़रूरी है. Connected Apps Platform, कॉन्टेक्स्ट विंडो की सीमाओं, एक्ज़ीक्यूशन लेटेंसी, और मॉडल के रीज़निंग चरणों के बारे में सुरक्षा के उपाय लागू करता है. इन सुरक्षा उपायों का पालन करने के लिए, इन दिशा-निर्देशों का पालन करें:

  • बैकएंड पर फ़िल्टर करना और खास जानकारी देना. Google के लागू प्रॉडक्ट को जवाब देने से पहले, अपने एमसीपी सर्वर पर बड़े डेटा स्ट्रीम को हमेशा फ़िल्टर करें, पहले से एग्रीगेट करें या खास जानकारी दें.
  • रॉ डंप से बचें. टूल के रिटर्न पेलोड में, रॉ डेटाबेस की लाइनें या इंडेक्स नहीं किए गए पूरे लॉग कभी न डालें.

अंदरूनी और मेटा टूल को शामिल न करें

अपने सर्वर के tools/list रिस्पॉन्स में, सिर्फ़ मॉडल के लिए उपलब्ध सुविधाओं को एक्सपोज़ करें:

  • सहायक टूल फ़िल्टर करना: ऐसे किसी भी इंटरनल, एडमिन या मेटा टूल को शामिल न करें जिन्हें मॉडल को कॉल नहीं करना है. उदाहरण के लिए, सर्वर की परफ़ॉर्मेंस की जांच करने वाले टूल, इंटरनल सेटअप रूटीन या डेवलपर यूटिलिटी हेल्पर.
  • कॉन्टेक्स्ट विंडो की परफ़ॉर्मेंस: ग़ैर-ज़रूरी टूल हटाने से, आपका एमसीपी स्कीमा छोटा रहता है. इससे कॉन्टेक्स्ट विंडो में टोकन की खपत कम होती है और मॉडल को टूल-रूटिंग में कोई भ्रम नहीं होता. समीक्षा के दौरान, ऐसे एमसीपी सर्वर फ़्लैग किए जाएंगे जिनमें दर्जनों टूल या गहराई से नेस्ट किए गए 'मेगा-टूल' स्कीमा मौजूद होंगे. ऐसा इसलिए किया जाएगा, ताकि उन्हें ठीक किया जा सके.

टूल की ग्रैन्युलैरिटी के लिए क्या करें और क्या न करें

यहां दिए गए उदाहरणों में, टूल के नाम रखने और ग्रैन्युलैरिटी के इस्तेमाल से जुड़े दिशा-निर्देशों के बारे में बताया गया है.

सुझाव इसका सुझाव नहीं दिया जाता

साफ़ तौर पर बताए गए नाम और पैरामीटर वाले टूल

हर टूल के लिए इनपुट स्कीमा तय होता है. अगर एलएलएम को कोई उपयोगकर्ता बनाना है, तो उसे एक ईमेल पता देना होगा. अगर उसे मिटाना है, तो आपको एक आईडी देना होगा. इसमें कोई अंदाज़ा नहीं लगाया जाता.

...
@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}"

    ...

टूल का नाम: manage_user

जानकारी: "उपयोगकर्ताओं को जोड़ने, अपडेट करने, मिटाने या उनकी जानकारी वापस पाने के लिए, इस टूल का इस्तेमाल करें."

...
@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"
    """
    ...

सुरक्षा के लिए टूल एनोटेशन का एलान करना

टूल की परिभाषाओं में प्रोटोकॉल एनोटेशन कॉन्फ़िगर करें, ताकि टूल के काम करने के तरीके के बारे में बताया जा सके. साथ ही, लागू होने वाले Google प्रॉडक्ट में पहले से मौजूद सुरक्षा सुविधाओं को ट्रिगर किया जा सके:

  • रनटाइम के दौरान पुष्टि करने वाले गेट: Google के लागू होने वाले प्रॉडक्ट, annotations.destructiveHint: true और annotations.openWorldHint: true का इस्तेमाल मुख्य फ़्लैग के तौर पर करते हैं. इससे रनटाइम के दौरान, उपयोगकर्ता से पुष्टि करने के लिए प्रॉम्प्ट ट्रिगर होते हैं. स्टेट-चेंजिंग, राइट या डिस्ट्रक्टिव कार्रवाइयों पर destructiveHint: true का एलान करें. साथ ही, ओपन-वर्ल्ड या बाहरी एनवायरमेंट के साथ इंटरैक्ट करने वाले टूल के लिए openWorldHint: true सेट करें, ताकि कार्रवाई करने से पहले, उपयोगकर्ता से पुष्टि करने के लिए कहा जा सके.
  • सिर्फ़ पढ़ने के लिए उपलब्ध क्वेरी हिंट: क्वेरी टूल पर readOnlyHint: true सेट करें. इससे बैकएंड की स्थिति में बदलाव किए बिना, सिर्फ़ डेटा फ़ेच किया जा सकेगा.
  • साफ़ तौर पर एनोटेशन की डिफ़ॉल्ट वैल्यू: मॉडल कॉन्टेक्स्ट प्रोटोकॉल की खास जानकारी के मुताबिक, readOnlyHint को शामिल न करने पर क्लाइंट, सुरक्षा के लिए डिफ़ॉल्ट रूप से readOnlyHint: false और destructiveHint: true को मान लेते हैं. सभी टूल पर एनोटेशन का साफ़ तौर पर एलान करने से, मॉडल की रूटिंग का अनुमान लगाया जा सकता है और उसे सही तरीके से सुरक्षित रूप से चलाया जा सकता है.

टूल के ब्यौरे

मॉडल के पास सिर्फ़ ब्यौरा होता है. इससे वह यह तय करता है कि आपका टूल मौजूदा समस्या को हल कर सकता है या नहीं. ब्यौरे लिखने के लिए, इन दिशा-निर्देशों का पालन करें:

टिप्पणियां नहीं, निर्देश लिखें

टूल के ब्यौरे को निर्देशों के तौर पर लिखें, न कि कोड की टिप्पणियों के तौर पर. कोड की टिप्पणियां अक्सर पैसिव होती हैं. एलएलएम, निर्देशों के हिसाब से बेहतर जवाब देते हैं.

"कैसे" के बारे में बताएं

अच्छे ब्यौरे से, "मेरे पास एक टूल है" और "मुझे पता है कि इस टूल को बातचीत में कैसे इस्तेमाल करना है" के बीच का अंतर कम होता है.

"वजह" बताएं

इस टूल को मिलते-जुलते टूल से अलग करें. उदाहरण के लिए, "इसका इस्तेमाल संगठन के उपयोगकर्ताओं के लिए करें और बाहरी उपयोगकर्ताओं के लिए customer_update का इस्तेमाल करें".

मॉडल को बताएं कि आर्ग्युमेंट कहां से मिलेंगे. उदाहरण के लिए, "order_search टूल से".

फ़ॉर्मैट तय करें

इकाइयां (मीटर बनाम फ़ीट) और फ़ॉर्मैट (आईएसओ तारीखें, सिमैंटिक वर्शन) तय करें.

मॉडल के विवेक से बचें

मॉडल को "सबसे सही फ़ैसले" का इस्तेमाल करने या बिना निर्देश वाली वैकल्पिक कार्रवाइयों का सुझाव देने के लिए न कहें.

टूल के ब्यौरे के उदाहरण

यहां दिए गए उदाहरणों में, टूल के ब्यौरे लिखने के लिए क्या करना चाहिए और क्या नहीं, इसके बारे में बताया गया है.

सुझाव इसका सुझाव नहीं दिया जाता

सही और पूरी जानकारी का सोर्स

"किसी उपयोगकर्ता का ईमेल पता अपडेट करता है. search_users टूल से मिले यूयूआईडी 'id' का ही इस्तेमाल करें. यूज़र आईडी का अनुमान न लगाएं."

(यह साफ़ तौर पर एक टूल के आउटपुट को इस टूल के इनपुट से लिंक करता है.)

"उपयोगकर्ता का ईमेल पता अपडेट करता है."

(मॉडल, 12345 जैसा कोई आईडी अनुमान लगा सकता है.)

फ़ॉर्मैट और पाबंदी

"मीटिंग शेड्यूल करना. 'date' की वैल्यू, ISO 8601 फ़ॉर्मैट (YYYY-MM-DD) में होनी चाहिए. अगर उपयोगकर्ता 'कल' या किसी अन्य संदर्भ का इस्तेमाल करता है, तो मौजूदा संदर्भ के आधार पर तारीख का हिसाब लगाएं."

"दी गई तारीख के लिए मीटिंग शेड्यूल करो."

(किसी व्यक्ति को सही लगता है (उदाहरण के लिए, "कल"), लेकिन स्कीमा की पुष्टि नहीं हो पाती ("2025-10-12" की ज़रूरत है))

आउटपुट से जुड़ी उम्मीदें

"सर्वर लॉग वापस लाता है. यह रॉ टेक्स्ट की आखिरी 50 लाइनें दिखाता है. विश्लेषण के लिए, कम समयसीमा का अनुरोध करें, ताकि टोकन की सीमाएं पार न हों."

"सर्वर लॉग पाएं."

(मॉडल किसी टूल को कॉल करके, उससे खास जानकारी देने के लिए कह सकता है. इसके बाद, उसे 5 एमबी का रॉ JSON डंप मिल सकता है. इससे उपयोगकर्ता को खराब अनुभव मिल सकता है.)

 
@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...

    ...

यह ब्यौरा, एक मिनी-मैन्युअल की तरह काम करता है. यह सोर्स (आईडी कहां से मिलेगा), पाबंदियों (मान्य enum), और कार्रवाई को मैनेज करता है.

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

यह सारा काम करने के लिए, वैरिएबल के नामों पर निर्भर करता है. इससे मॉडल को "status" की मान्य वैल्यू का अनुमान लगाना पड़ता है

टूल के पैरामीटर

टूल के बारे में बताने के साथ-साथ, पैरामीटर के बारे में भी बताएं, ताकि उन्हें समझने में कोई परेशानी न हो.

एक्सप्लिसिट टाइप

मज़बूत और खास टाइप इस्तेमाल करें (string, integer, boolean, array).

वैल्यू के तय सेट के लिए, enum का इस्तेमाल करें

अगर कोई पैरामीटर सिर्फ़ वैल्यू के तय सेट को स्वीकार करता है (उदाहरण के लिए, daylight, cool, warm), तो उन्हें enum कलेक्शन में शामिल करें. इससे, सटीक जानकारी देने की इसकी क्षमता काफ़ी बढ़ जाती है.

ज़रूरी पैरामीटर के बारे में साफ़ तौर पर बताएं

साफ़ तौर पर बताएं कि फ़ंक्शन को काम करने के लिए कौनसे पैरामीटर ज़रूरी हैं.

सिमैंटिक स्कीमा मैचिंग लागू करना

अपने ऐप्लिकेशन को इंटिग्रेट करते समय, आपको अपने टूल के पैरामीटर से मैच करने वाले सेमैंटिक स्कीमा की ज़रूरत पड़ सकती है. यह स्कीमा उस वर्टिकल के लिए होना चाहिए जिसके लिए ऐप्लिकेशन डेवलप किया जा रहा है. शामिल होने की प्रोसेस के दौरान, आपको वर्टिकल स्कीमा (एक JSON स्कीमा) मिलेगा.

टूल के पैरामीटर के उदाहरण

यहां दिए गए उदाहरणों में, टूल के पैरामीटर को मैनेज करने के लिए क्या करना चाहिए और क्या नहीं, इसके बारे में बताया गया है.

सुझाव इसका सुझाव नहीं दिया जाता

आर्ग्युमेंट के फ़ॉर्मैट और इकाइयां

radius: "मीटर में दायरा. यह 0 से बड़ा फ़्लोट होना चाहिए."

(इससे यूनिट के बारे में गलत जानकारी देने से बचा जा सकता है)

radius: "सर्कल की त्रिज्या."

आईडी के फ़ॉर्मैट और कॉन्टेक्स्ट

user_id: "डेटाबेस का यूयूआईडी (उदाहरण के लिए, 550e8400-e29b...). यहां ईमेल पते न डालें."

ध्यान दें: सबसे सही तरीके के तौर पर, अंकों वाले सभी आईडी फ़ील्ड को स्ट्रिंग वैल्यू के तौर पर माना जाना चाहिए. खास तौर पर, अगर आपका आईडी 10 से ज़्यादा अंकों का हो सकता है, तो इस बात का जोखिम रहता है कि इंटरनल सिस्टम उसे छोटा कर दे (32 बिट कंटेनर में फ़ोर्स कर दे). साथ ही, आने वाले समय में टूल कॉल के लिए, मॉडल इस वर्शन का इस्तेमाल करे.

(टाइप से जुड़ी गड़बड़ियों को रोकता है)

user_id: "उपयोगकर्ता का आईडी."

रिटर्न वैल्यू से जुड़ी उम्मीदें

"रिकॉर्ड को अपडेट करता है और नए टाइमस्टैंप के साथ अपडेट किया गया JSON ऑब्जेक्ट दिखाता है."

(इससे मॉडल को पता चलता है कि बदलाव की पुष्टि करने के लिए, "अपडेट" के तुरंत बाद "गेट" टूल को कॉल करने की ज़रूरत नहीं है.)

"रिकॉर्ड अपडेट करता है."

 

@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."""
    ...

एलएलएम को यह नहीं पता कि "क्वेरी" किस सिंटैक्स के साथ काम करती है (एसक्यूएल? रेगुलर एक्सप्रेशन? सादा टेक्स्ट?) इसे नहीं पता कि ज़्यादा से ज़्यादा "सीमा" क्या है.

जवाब और गड़बड़ी को ठीक करना

जवाब ही अगला प्रॉम्प्ट है के मुख्य सिद्धांत के मुताबिक, टूल अपने एक्ज़ीक्यूशन के नतीजे को डेटा पेलोड के तौर पर दिखाता है. इसके बाद, इसे सीधे एलएलएम की कॉन्टेक्स्ट विंडो में पेस्ट किया जाता है. नतीजे की सफलता या असफलता से तय होता है कि आगे क्या होगा:

  • अगर यह सफल होता है: मॉडल को रिटर्न वैल्यू की ज़रूरत होती है, ताकि वह जान सके कि क्या हुआ और अगला कदम तय कर सके.
  • अगर यह काम नहीं करता है: मॉडल को यह जानना होगा कि यह काम क्यों नहीं कर रहा है और इसे कैसे ठीक करें. क्रैश (500 गड़बड़ी) होने पर बातचीत रुक जाती है. गड़बड़ी का मैसेज ज़्यादा जानकारी देने वाला होने पर, मॉडल को खुद को ठीक करने में मदद मिलती है.

आपके टूल का लॉजिक सफल हो या न हो, आपको रिटर्न वैल्यू पेलोड को फ़ॉर्मैट करना होगा, ताकि मॉडल उसे आसानी से पार्स कर सके. रिस्पॉन्स पेलोड को पैकेज करते समय, इन सबसे सही तरीकों को अपनाएं.

JSON का इस्तेमाल करना

स्ट्रक्चर्ड डेटा को TextContent में फ़ॉर्मैट करें (अस्थायी पाबंदी). structuredContent, फ़िलहाल Connected Apps Platform के साथ काम नहीं करता. इसलिए, अपने डेटा को मैन्युअल तरीके से सीरियलाइज़ करें. भले ही, आपको एक सामान्य सूची दिखानी हो, json.dumps().

जवाब में यूआरएल शामिल करना

नतीजों में दिखाए जाने वाले यूआरएल छोटे होने चाहिए और उनमें ज़्यादा पैरामीटर नहीं होने चाहिए. हमारा सुझाव है कि यूआरएल छोटा करने वाली सेवाओं का इस्तेमाल करें. इससे टोकन की संख्या कम होगी और ग़लत या गुमराह करने वाली जानकारी का जोखिम भी कम होगा.

सेल्फ़-डिस्क्रिप्टिव एंटी-हैलुसिनेशन पेलोड

रॉ कोड या इंटरनल आईडी को हमेशा ऐसे डिसप्ले नेम के साथ जोड़ें जिन्हें कोई भी व्यक्ति आसानी से पढ़ सके. साथ ही, मेज़रमेंट की साफ़ तौर पर बताई गई इकाइयां और रेफ़रंस रेंज भी शामिल करें. कंप्रेस की गई डिक्शनरी की ऐसी कुंजियां या मैप नहीं किए गए न्यूमेरिक कोड कभी न दिखाएं जिनकी वजह से मॉडल को कॉन्टेक्स्ट का अनुमान लगाना पड़े.

गड़बड़ी को ठीक करने के लिए बेहतर तरीके अपनाएं

गड़बड़ी के साफ़ और काम के मैसेज दिखाएं, ताकि मॉडल को पता चल सके कि क्या गड़बड़ी हुई है और वह उपयोगकर्ता को इसकी जानकारी दे सके. एमसीपी की गड़बड़ी ठीक करने के बारे में जानकारी देखें.

try/except का इस्तेमाल करना

टूल के लॉजिक को try/except ब्लॉक में रैप करें और स्ट्रिंग के तौर पर गड़बड़ियां दिखाएं.

गड़बड़ियों को ठीक करने के लिए ज़रूरी जानकारी देना

गड़बड़ी के मैसेज में अगला चरण सुझाएं. उदाहरण के लिए, "पहले टूल X का इस्तेमाल करके देखें".

क्रियाओं की पुष्टि करें

साइड-इफ़ेक्ट वाले टूल (बनाएं/अपडेट करें/मिटाएं) के लिए, खाली स्ट्रिंग न दिखाएं.

जवाबों और गड़बड़ी को ठीक करने के उदाहरण

यहां दिए गए उदाहरणों में, जवाबों और गड़बड़ी को ठीक करने के बारे में बताया गया है.

सुझाव इसका सुझाव नहीं दिया जाता

एक्सप्लिसिट सीरियलाइज़ेशन


...
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)

पकड़ें और जानकारी दें


...
@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."

तकनीकी तौर पर, टूल "सफल" होता है (स्ट्रिंग दिखाता है), लेकिन स्ट्रिंग में गड़बड़ी की जानकारी होती है. मॉडल इसे पढ़ता है और उसे पता चलता है कि "ओह, यह आईडी मौजूद नहीं है." इसके बाद, वह उपयोगकर्ता से सही आईडी मांग सकता है.) 


...
@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 काम नहीं करता है, तो सर्वर 500 कोड वाली गड़बड़ी दिखाता है. एलएलएम को कोड चलाने में गड़बड़ी का एक सामान्य मैसेज मिलता है. हालांकि, उसे इसकी वजह नहीं पता होती. जैसे, क्या आईडी गलत था? क्या डेटाबेस डाउन है? अनुमति नहीं दी गई?). यह फिर से वही गलत इनपुट देने की कोशिश करेगा.)

कोई जवाब नहीं दिया गया

...
@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.

एलएलएम अक्सर खाली जवाबों से भ्रमित हो जाते हैं. ऐसा हो सकता है कि वे "टूल काम नहीं कर रहा" जैसा भ्रम पैदा करें या कॉल को दोहराएं.

खुद के बारे में बताने वाला और गलत जानकारी को रोकने वाला पेलोड

रॉ कोड या इंटरनल आईडी को हमेशा ऐसे डिसप्ले नेम के साथ जोड़ें जिन्हें कोई भी व्यक्ति आसानी से पढ़ सके. साथ ही, मेज़रमेंट की साफ़ तौर पर बताई गई इकाइयां और सामान्य रेफ़रंस रेंज भी शामिल करें.

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

(इससे मॉडल को यह पता चलता है कि वैल्यू का असल मतलब क्या है. साथ ही, उसे इकाइयों या रेफ़रंस थ्रेशोल्ड का अनुमान लगाने की ज़रूरत नहीं पड़ती.)

रॉ आईडी, कस्टम कंप्रेशन या मैप नहीं किए गए कोड

बिना लेबल के रॉ इंटरनल आईडी, कस्टम डिक्शनरी के संक्षिप्त नाम या न्यूमेरिक कोड दिखाना.

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

(इससे मॉडल को यह अनुमान लगाना पड़ता है कि 105 का क्या मतलब है. इस वजह से, मॉडल गलत इकाइयां बता सकता है, ज़रूरी जानकारी को छोड़ सकता है या गलत जानकारी दे सकता है.)

एमसीपी से जुड़ी गड़बड़ी को ठीक करना

गड़बड़ियों को सही तरीके से ठीक करना ज़रूरी है.

  • ठीक की जा सकने वाली गड़बड़ियों (जैसे, अमान्य यूज़र आईडी या ज़रूरी नहीं होने वाले पैरामीटर का मौजूद न होना) के लिए, टूल के जवाब में गड़बड़ी की जानकारी देने वाली सामान्य टेक्स्ट स्ट्रिंग दिखाएं. इससे मॉडल को सुझाव/राय या शिकायत की जांच करने, गड़बड़ी को समझने, और उसे खुद ठीक करने या उपयोगकर्ता से ज़्यादा जानकारी मांगने में मदद मिलती है.
  • टर्मिनल की गड़बड़ियों (जैसे, अनुरोध संख्या सीमित करना, पुष्टि या अनुमति से जुड़ी गड़बड़ियां या बैकएंड सर्वर का बंद होना) के लिए, गड़बड़ी के सही कोड के साथ McpError दिखाएं. इससे प्लैटफ़ॉर्म, गड़बड़ी को व्यवस्थित तरीके से मैनेज कर पाएगा.

गड़बड़ी के रिस्पॉन्स की बॉडी का उदाहरण (JSON)

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

Message में, एमसीपी के ErrorData फ़ील्ड का JSON डंप होता है. सही code और मॉडल को दिखने वाला message वापस करके, Connected Apps Platform, गड़बड़ी का मैसेज पढ़ सकता है. साथ ही, उपयोगकर्ता को नैचुरल लैंग्वेज में मददगार जानकारी दे सकता है. उदाहरण के लिए, "माफ़ करें, मुझे उस आईडी से जुड़ी जगह नहीं मिली. क्या आप नाम की जांच कर सकते हैं?"

एमसीपी, क्लाइंट को JSON-RPC 2.0 स्पेसिफ़िकेशन का इस्तेमाल करके, एमसीपी सर्वर से कनेक्ट करने की अनुमति देता है. JSON-RPC में, आम तौर पर होने वाली गड़बड़ियों के लिए पहले से तय की गई कुछ गड़बड़ियां भेजी जाती हैं. जैसे, अमान्य अनुरोध, पार्स करने से जुड़ी गड़बड़ियां वगैरह. इस गाइड में बताया गया है कि एमसीपी सर्वर, कस्टम गड़बड़ियां कैसे भेज सकते हैं.

स्टेटस
कोड		 मैसेज इस्तेमाल क्या आपको
साफ़ तौर पर
कोई वैल्यू रिटर्न करनी है?
उपयोगकर्ता/ग्राहक से जुड़ी गड़बड़ियां
-32300 USER_RATE_LIMITED उपयोगकर्ता ने इस्तेमाल करने की सीमा पूरी कर ली है. हां
-32301 MISSING_REQUIRED_INFORMATION इनपुट अनुरोध में सभी ज़रूरी जानकारी मौजूद नहीं है हां
-32302 USER_PERMISSION_DENIED उपयोगकर्ता ने टूल इस्तेमाल करने की अनुमति नहीं दी. उदाहरण के लिए, उपयोगकर्ता के पास काम से जुड़ा खाता होना चाहिए, उम्र से जुड़ी पाबंदी होनी चाहिए, स्थान-भाषा होनी चाहिए वगैरह या टूल की एंटरप्राइज़ सदस्यता नहीं होनी चाहिए. हां
ऐप्लिकेशन से जुड़ी गड़बड़ियां/कारोबारी नियम से जुड़ी गड़बड़ियां
-32400 RUNTIME_ERROR सर्वर कोड एक्ज़ीक्यूशन की वजह से गड़बड़ी हुई हां
-32401 NULL_POINTER_EXCEPTION किसी शून्य पॉइंटर/ऑब्जेक्ट को चलाने की कोशिश करना हां
-32402 OUT_OF_MEMORY सर्वर कोड में किसी ऑब्जेक्ट को असाइन करने के लिए, ज़रूरत के मुताबिक मेमोरी नहीं है हां
इंफ़्रास्ट्रक्चर से जुड़ी गड़बड़ियां
-32500 DEADLINE_EXCEEDED अनुरोध को पूरा होने में तय समय से ज़्यादा लग रहा है. ऐसा कई वजहों से हो सकता है. जैसे, सर्वर पर ज़्यादा लोड होना, नेटवर्क से जुड़ी समस्याएं वगैरह. हां
-32501 RESOURCE_EXHAUSTED सर्वर में आउट ऑफ़ मेमोरी, डिस्क में बचा स्टोरेज, थ्रेड, सीपीयू समय वगैरह नहीं बचा है. हां
-32502 SERVICE_UNAVAILABLE डिपेंडेंट सेवा (जैसे, कोई दूसरी माइक्रोसर्विस, डेटाबेस, कैश मेमोरी वगैरह) उपलब्ध नहीं है हां
JSON-RPC से जुड़ी गड़बड़ियां (ये गड़बड़ियां, एमसीपी ट्रांसपोर्ट का हिस्सा हैं)
-32700 PARSE_ERROR सर्वर, अनुरोध को पार्स नहीं कर सका नहीं
-32600 INVALID_REQUEST क्लाइंट का अनुरोध गलत है नहीं
-32601 METHOD_NOT_FOUND एमसीपी टूल का नाम अमान्य है नहीं
-32602 INVALID_PARAMS अनुरोध के पैरामीटर अमान्य हैं. इनमें पैरामीटर मौजूद नहीं हैं या पैरामीटर के टाइप मेल नहीं खाते नहीं
-32603 INTERNAL_ERROR डिफ़ॉल्ट जवाब नहीं

यहां एक उदाहरण दिया गया है, जिसमें आधिकारिक Python SDK टूल (mcp) का इस्तेमाल करके, अपने सर्वर में एमसीपी गड़बड़ी को ट्रिगर करने का तरीका बताया गया है. ErrorData पेलोड वाला McpError ट्रिगर करें. SDK टूल, इसे गड़बड़ी की स्थिति के साथ, JSON-RPC गड़बड़ी के ज़रूरी फ़ॉर्मैट में अपने-आप क्रम से लगा देता है.

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."
    ),
  )

टूल कॉन्टेक्स्ट

Google के कुछ प्रॉडक्ट, टूल कॉन्टेक्स्ट एपीआई के साथ काम करते हैं. इससे एमसीपी सर्वर को सिग्नल भेजे जा सकते हैं. इस एपीआई का इस्तेमाल, संवेदनशील जानकारी की ज़रूरत वाले मामलों में किया जाता है. उदाहरण के लिए, ऐसा मेटाडेटा जो टूल की मुख्य परिभाषा का हिस्सा नहीं है. जैसे, उन टूल के लिए स्थानीय भाषा की जानकारी जिन्हें स्थानीय भाषा में उपलब्ध कराने की ज़रूरत होती है. टूल कॉन्टेक्स्ट एपीआई को सिर्फ़ Connected Console के ज़रिए ऐक्सेस किया जा सकता है.

Connected Console में अपने ऐप्लिकेशन के साथ current_user_location_fine जैसा कोई सिग्नल रजिस्टर करने पर, Google के लागू होने वाले प्रॉडक्ट, MCP tools/call के अनुरोधों को बेहतर बनाएंगे. इसके लिए, वे अनुरोध किया गया डेटा उपलब्ध कराने वाली एक अतिरिक्त _meta एंट्री जोड़ेंगे. इन सिग्नल का इस्तेमाल किया जा सकता है:

  • current_user_location_fine (सिर्फ़ Gemini के लिए, अनुमति वाले वर्टिकल के लिए)
  • 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"
      }
    }
  }
}

इस डेटा को अनपैक करने के लिए:

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)"

उपयोगकर्ता अनुभव की रेंडरिंग

एमसीपी वाले ऐप्लिकेशन

Google के कुछ प्रॉडक्ट, एमसीपी ऐप्लिकेशन इंटिग्रेशन के साथ काम करते हैं. इससे उपयोगकर्ताओं को अपनी पसंद के मुताबिक यूज़र इंटरफ़ेस बनाने की सुविधा मिलती है. इंटिग्रेशन से जुड़े सामान्य निर्देशों के लिए, स्पेसिफ़िकेशन का पालन करें.

Google के चुनिंदा प्रॉडक्ट पर एमसीपी ऐप्लिकेशन इंटिग्रेट करने पर, ये चेतावनियां मिलती हैं.

रजिस्ट्रेशन के समय संसाधन डालना

Google के लागू होने वाले प्रॉडक्ट, टूल को शामिल करने के दौरान यूज़र इंटरफ़ेस (यूआई) के संसाधनों को फ़ेच करते हैं. यह टूल की सूची और टूल के ब्यौरे की तरह ही होता है. इसका मतलब है कि JavaScript में किए गए बदलावों जैसे किसी भी संसाधन के अपडेट अपने-आप नहीं दिखेंगे. इसके लिए, टूल को फिर से डेटा डालना होगा.

यूआई से जुड़े किसी एक संसाधन का साइज़ 15 एमबी से ज़्यादा नहीं होना चाहिए. साथ ही, आपके सर्वर पर मौजूद यूआई से जुड़े सभी संसाधनों का कुल साइज़ 100 एमबी से ज़्यादा नहीं होना चाहिए.

यूज़र इंटरफ़ेस (यूआई) के संसाधनों के लिए, इनमें से किसी एक एमआईएमई टाइप का इस्तेमाल करना ज़रूरी है: text/html, text/javascript, text/css या text/html;profile=mcp-app. झलक देखने के लिए पुश करते समय, नॉन-स्टैंडर्ड या प्लैटफ़ॉर्म के हिसाब से एमआईएमई टाइप की पुष्टि नहीं हो पाएगी.

सीएसपी के दिशा-निर्देश

Google के लागू होने वाले प्रॉडक्ट, एमसीपी ऐप्लिकेशन की आधिकारिक शर्तों का पालन करते हैं. इनमें सीएसपी [1], [2] शामिल हैं. साथ ही, सीएसपी के डायरेक्टिव का उल्लंघन करने वाले किसी भी अनुरोध को ब्लॉक कर दिया जाएगा.

अगर Google के लागू होने वाले प्रॉडक्ट इस्तेमाल किए जा रहे हैं, तो सीएसपी में blob: और data: को भी जोड़ना ज़रूरी है. इन्हें डिफ़ॉल्ट रूप से नहीं जोड़ा जाएगा. यह डेवलपर पर निर्भर करता है कि वह उन्हें सीएसपी में जोड़े या नहीं.

Script-src एक अपवाद है

हम सिर्फ़ इन डायरेक्टिव की अनुमति देते हैं: unsafe-inline (डिफ़ॉल्ट रूप से जोड़ा गया), wasm-unsafe-eval, और data: (अगर resource_domains में शामिल है). अगर iframe बाहरी स्क्रिप्ट लोड कर रहा है, तो इसे हल करने के लिए, JS को एचटीएमएल में बंडल करें या सब-रिसोर्स इंटिग्रिटी (एसआरआई) हैश का इस्तेमाल करें.

  • पहला विकल्प: एचटीएमएल में इनलाइन / बंडल जेएस (सबसे आसान)

    • JS कोड बंडल करना:

      • यूज़र इंटरफ़ेस (यूआई) रिसॉर्स के लिए दिखाए गए एचटीएमएल पेलोड में, component-init.js के कॉन्टेंट को सीधे <script> टैग के अंदर इनलाइन करें:

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

    • रिमोट <script src> टैग हटाएं

      • एचटीएमएल दस्तावेज़ से <script src="https://api.mycompany.com/..."> रेफ़रंस मिटाएं.

    • फिर से शामिल करने / अपडेट करने वाला टूल

  • दूसरा विकल्प: सब-रिसोर्स इंटिग्रिटी (एसआरआई) हैश का इस्तेमाल करना:

    इसका इस्तेमाल तब करें, जब स्क्रिप्ट को https://api.company.com/... पर बाहरी तौर पर होस्ट करना ज़रूरी हो.

    • स्क्रिप्ट के SHA-256 हैश की गणना करना
      • component-init.js का base64 SHA-256 हैश जनरेट करें
    • resourceDomains में हैश जोड़ें (integrity एट्रिब्यूट से मैच करने के लिए, sha256- प्रीफ़िक्स को शामिल करना ज़रूरी है)
    • एचटीएमएल <script> टैग अपडेट करें
      • एचटीएमएल विजेट में स्क्रिप्ट टैग में integrity और crossorigin एट्रिब्यूट जोड़ें
    • सीडीएन/सर्वर पर सीओआरएस हेडर की पुष्टि करना
      • पक्का करें कि api.company.com, component-init.js को Access-Control-Allow-Origin: * के साथ उपलब्ध कराए या scf.usercontent.goog की अनुमति दे, ताकि ब्राउज़र एसआरआई की पुष्टि के लिए रिस्पॉन्स के मुख्य हिस्से को पढ़ सके.
    • फिर से शामिल करने / अपडेट करने वाला टूल

एमसीपी टूल के ब्यौरे के लिए सुरक्षा से जुड़े दिशा-निर्देश

ब्यौरा ही वह एकमात्र कॉन्टेक्स्ट है जिससे मॉडल को टूल की क्षमताओं के बारे में पता चलता है. इसलिए, ब्यौरे को सटीक और सुरक्षित तरीके से लिखा जाना चाहिए, ताकि टूल अनचाहे तरीके से काम न करे. अपने टूल की जानकारी का ड्राफ़्ट तैयार करते समय, इन दिशा-निर्देशों का पालन करें.

  • फ़ंक्शन के बारे में बताएं, लेकिन व्यवहार को डिक्टेट न करें. ब्यौरे में सटीक तौर पर बताया जाना चाहिए कि टूल क्या करता है. इसमें मॉडल को आगे की कार्रवाइयां करने का निर्देश नहीं दिया जाना चाहिए.
  • स्कोप और ज़रूरी शर्तें तय करें. टूल का मुख्य लक्ष्य, इसके इस्तेमाल की खास स्थितियां (कब), और सभी ज़रूरी इनपुट (पैरामीटर/आर्ग्युमेंट) साफ़ तौर पर बताएं.
  • पक्का करें कि जानकारी सही हो. ब्यौरे में टूल के कोड के बारे में सही जानकारी होनी चाहिए. अगर कोई टूल, डेटा लिखने या मिटाने की कार्रवाई करता है, तो यह दावा न करें कि वह सिर्फ़ पढ़ने के लिए है.

सुरक्षा से जुड़े जोखिम और उनसे बचने का तरीका

जोखिम वाला इलाका सुझाव इस तरीके का इस्तेमाल बिलकुल न करें

प्रॉम्प्ट इंजेक्शन

टूल के मकसद और फ़ंक्शन के बारे में साफ़ तौर पर बताने के लिए, ऑब्जेक्टिव और डिक्लेरेटिव भाषा का इस्तेमाल करें.

मॉडल के व्यवहार को बदलने या सिस्टम फ़्लो में बदलाव करने के लिए, ज़रूरी निर्देश इस्तेमाल करना. उदाहरण के लिए, "आपको यह कहना होगा...", "दौड़ने के बाद, आपको..."). 'ज़रूरी है' या 'अहम' जैसे शब्दों का इस्तेमाल सिर्फ़ तब किया जा सकता है, जब स्ट्रक्चर्ड पैरामीटर की पाबंदियों या इस्तेमाल के नियमों को तय किया जा रहा हो.

टूल की जानकारी वाले टेक्स्ट के लिए, स्टैंडर्ड और सामान्य फ़ॉर्मैटिंग का इस्तेमाल करें.

ध्यान खींचने वाली फ़ॉर्मैटिंग का इस्तेमाल करना —उदाहरण के लिए, कैपिटल लेटर का ज़्यादा इस्तेमाल करना और VERY IMPORTANT: या **CRITICAL** जैसे टैग इस्तेमाल करना.

सिर्फ़ टूल के फ़ंक्शन और उसके काम करने के तरीके पर फ़ोकस करें.

रोल-प्ले करने के निर्देश या पिछले निर्देशों को अनदेखा करने के निर्देश शामिल हों.

टूल शैडोइंग और हाइजैकिंग

पक्का करें कि ब्यौरा सटीक हो और उसमें टूल की असल और काम की सुविधाओं के बारे में ही बताया गया हो.

टूल के ब्यौरे को बहुत ज़्यादा सामान्य या अस्पष्ट बनाना या यह दावा करना कि एक ही टूल, कई अलग-अलग काम करता है.

टूल के लिए कोई यूनीक, जानकारी देने वाला, और समझदारी भरा नाम चुनें.

किसी भरोसेमंद टूल के नाम में थोड़ा बदलाव करके इस्तेमाल करना या सामान्य नाम का इस्तेमाल करना. उदाहरण के लिए, do_everything_tool, assistant_tool.

अपने ब्यौरे में, अन्य ऐप्लिकेशन या बाहरी प्लैटफ़ॉर्म के टूल का नाम न लें.

अन्य टूल का साफ़ तौर पर रेफ़रंस देना या अन्य टूल को कब या कैसे इस्तेमाल करना चाहिए, इसके लिए नए नियम बनाना.

मॉडल के प्लानर को उपयोगकर्ता के कॉन्टेक्स्ट के आधार पर, सबसे सही टूल चुनने की अनुमति दें.

ऐसी भाषा का इस्तेमाल करना जो प्रतिस्पर्धा को बढ़ावा देती हो या एसईओ से जुड़ा कोई ऐसा प्रॉम्प्ट शामिल करना जो मॉडल को आपके टूल को अन्य टूल से बेहतर दिखाने के लिए कहता हो.

ट्रिगर में बदलाव करना

ब्यौरे में, बातचीत के इतिहास में मौजूद सामान्य वाक्यांशों का रेफ़रंस या उन पर प्रतिक्रिया नहीं दी गई है.

ऐसा कंडीशनल लॉजिक बनाना जो उपयोगकर्ता के सामान्य और नुकसान न पहुंचाने वाले वाक्यांशों (उदाहरण के लिए, "धन्यवाद", "खास जानकारी देने के लिए") के आधार पर नुकसान पहुंचाने वाली कार्रवाई को ट्रिगर करता हो.

पैरामीटर का गलत इस्तेमाल

सिर्फ़ वे पैरामीटर तय करें जो टूल के फ़ंक्शन के लिए ज़रूरी हैं. साथ ही, इनपुट डेटा के हिसाब से नाम इस्तेमाल करें. उदाहरण के लिए, file_id, search_term.

फ़ंक्शन के पैरामीटर को ऐसे नामों के साथ तय करें जो एजेंट की अंदरूनी स्थिति को दिखाते हों. उदाहरण के लिए, system_prompt, conversation_history, full_context.

डेटा बाहर निकाला जाना

पूरी प्रोसेस के दौरान निजता की सुरक्षा को ध्यान में रखना - ऐसे आइडेंटिफ़ायर जिनका डेटा शेयर नहीं किया जाता और होस्ट की ओर से मैनेज की जाने वाली पुष्टि की प्रोसेस.

संवेदनशील आईडी का इस्तेमाल करें, न कि बिना हैश की गई व्यक्तिगत पहचान से जुड़ी जानकारी (पीआईआई) का. सभी डेटा को अनुमति वाली और सुरक्षित सीमाओं के अंदर ही मैनेज किया जाना चाहिए. साथ ही, सार्वजनिक जानकारी में यह नहीं बताया जाना चाहिए कि डेटा को बाहरी तौर पर भेजा गया है. टूल को चलाने के लिए, OAuth हैंडशेक के ज़रिए अनुमतियां अपने-आप मिल जाएंगी.

Google के प्रॉडक्ट को भेजने से पहले, किसी भी संवेदनशील जानकारी को हटा देना चाहिए.

उपयोगकर्ता से व्यक्तिगत पहचान से जुड़ी जानकारी (पीआईआई), स्वास्थ्य से जुड़ी निजी जानकारी (पीएचआई) या कोई अन्य निजी और/या संवेदनशील जानकारी, निजी या कारोबार का डेटा या इकाई का डेटा मांगना. ऐसा किसी भी तरह से करना, लागू होने वाले Google प्रॉडक्ट की सेवा की शर्तों का उल्लंघन है.

उपयोगकर्ता के किसी भी डेटा (क्वेरी, जगह की जानकारी, कॉन्टेक्स्ट) को बिना अनुमति वाले तीसरे पक्ष के यूआरएल, लॉगिंग सेवाओं या बाहरी सिस्टम पर भेजने के लिए कहना या उसे भेजना ज़रूरी बनाना.

फ़ंक्शन और नाम तय करने के सबसे सही तरीके

टूल के ब्यौरे को सुरक्षित रखने के अलावा, आपको यह पक्का करना होगा कि मॉडल, बिना किसी भ्रम के टूल को भरोसेमंद तरीके से चुन सके और उसे लागू कर सके. फ़ंक्शन और नाम रखने के लिए, यहां दिए गए सबसे सही तरीकों का पालन करें:

  • पैरामीटर की सटीक जानकारी. पक्का करें कि ब्यौरे में मौजूद सभी पैरामीटर के नाम और टाइप, टूल के असल फ़ंक्शन से पूरी तरह मैच करते हों.
  • सही नाम रखना. टूल के नाम से उसके फ़ंक्शन के बारे में साफ़ तौर पर पता चलना चाहिए. "execute" जैसे बहुत सामान्य नाम इस्तेमाल न करें. नाम ऐसा होना चाहिए जो टूल के बड़े नेटवर्क के साथ भी सही लगे.

अपेंडिक्स: इन्फ़्रास्ट्रक्चर और नेटवर्क को अनुमति वाली सूची में शामिल करना

अगर आपका होस्टिंग इन्फ़्रास्ट्रक्चर, एपीआई गेटवे या फ़ायरवॉल, सोर्स आईपी पते के हिसाब से इनकमिंग कनेक्शन को सीमित करता है, तो Google के इन आउटबाउंड सीआईडीआर ब्लॉक को अनुमति वाली सूची में शामिल करें:

  • 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

पक्का करें कि आपका एनवायरमेंट, एचटीटीपीएस पोर्ट 443 पर इन आईपी रेंज से आने वाले ट्रैफ़िक को अनुमति देता हो. इससे Google के लागू होने वाले प्रॉडक्ट, आपके रिमोट एमसीपी सर्वर तक पहुंच पाएंगे. इससे एमसीपी को शुरू करने, टूल खोजने, और अनुरोध को पूरा करने में मदद मिलेगी.