‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

הגדרת Model Context Protocol

במאמר הזה מוסבר איך להגדיר את API Gateway כך שיפעל כשרת Model Context Protocol‏ (MCP) מרוחק.

לפני שמתחילים

מוודאים שיש לכם מפרט OpenAPI 3.x תקין ל-API. אין תמיכה ב-MCP ב-OpenAPI 2.0.
חשוב להבין את העקרונות הבסיסיים של API Gateway.

אימות ההגדרות האישיות

כשמעלים את המפרט של OpenAPI, ‏API Gateway מבצע את האימותים הבאים להגדרת MCP:

מיקום: צריך לציין את התוסף x-google-mcp-tool רק ברמת הפעולה הספציפית.
שיטת HTTP: רק פעולות מסוג GET,‏ POST,‏ PUT,‏ PATCH ו-DELETE יכולות להיות חשופות ככלי MCP.
שם הכלי: שמות הכלים חייבים להתאים לביטוי הרגולרי [A-Za-z0-9_.-]{1,128} ולהיות ייחודיים בכל המפרט.
תיאור: לכל כלי חייב להיות תיאור לא ריק (שנלקח מהתיאור, מהסיכום או מהשינוי של הפעולה). פעולות בלי תיאור שניתן לפתור נדחות.
אבטחה: אם מגדירים אימות ל-tools/list, צריך לציין בדיוק סכמת אבטחה אחת שמוגדרת ב-components.securitySchemes. הסכימה יכולה להיות סכימת JWT או סכימת מפתח API. אם אתם משתמשים בסכימת JWT, אתם צריכים גם לתת לה שם בדרישת security ברמה העליונה של המפרט.

מודל האימות

‫API Gateway מחיל כללי אימות שונים בהתאם להפעלת ה-method של MCP:

מחזור החיים של הפרוטוקול: השיטות initialize ו-notifications/initialized הן ללא אימות.
הפעלת כלי (tools/call): שימוש חוזר במדיניות האימות שהוגדרה לפעולה הבסיסית במפרט OpenAPI. הוא אוכף את אותן דרישות של מפתח API או JWT כמו קריאה ישירה לנקודת הקצה של ה-REST.
גילוי כלים (tools/list): כברירת מחדל, השיטה הזו לא מאומתת. עם זאת, כשיטה מומלצת לאבטחה, מומלץ מאוד להגן על גילוי הכלים על ידי הפעלת אימות לשיטה הזו באמצעות tools-list.security. אתם יכולים לאמת את tools/list באמצעות JWT או מפתח API.

שלבים להגדרת MCP

כדי לחשוף את ה-API ככלי MCP, פועלים לפי השלבים הבאים:

1. זיהוי הפעולות שרוצים לחשוף

בודקים את מפרט ה-OpenAPI ומחליטים אילו פעולות צריכות להיות זמינות לסוכני ה-AI.

2. עדכון מפרט OpenAPI

אפשר להפעיל את MCP באופן גלובלי לכל הפעולות שעומדות בדרישות, או להגדיר אותו לכל פעולה בנפרד.

הפעלה גלובלית

כדי להפעיל את MCP באופן גלובלי, מוסיפים את השדה mcp ל-x-google-api-management ברמת המסמך:

openapi: 3.0.3
info:
  title: Bookstore API
  version: 1.0.0
x-google-api-management:
  mcp: true
  backends:
    bookstore-backend:
      address: https://bookstore-backend-12345678.us-central1.run.app

כשמפעילים את התכונה באופן גלובלי, כל הפעולות שעומדות בדרישות (על סמך השיטה והנתיב של ה-HTTP) נחשפות ככלי MCP. כברירת מחדל, שם הכלי הוא operationId של הפעולה, והתיאור הוא התיאור או הסיכום של הפעולה.

הגדרה לכל פעולה

אפשר לשנות את ההגדרות הגלובליות או לחשוף פעולות באופן סלקטיבי באמצעות x-google-mcp-tool:

paths:
  /v1/shelves/{shelf}:
    delete:
      operationId: deleteShelf
      summary: Delete a shelf.
      x-google-backend: bookstore-backend
      x-google-mcp-tool:
        name: delete_shelf
        description: "Permanently delete a shelf and every book on it."

אפשר גם לבטל את ההסכמה לפעולה כשהיא מופעלת באופן גלובלי על ידי הגדרת x-google-mcp-tool: false.

3. אימות `tools/list` (מומלץ)

כברירת מחדל, השיטה tools/list (שמפרטת את הכלים הזמינים) לא מאומתת. כשיטה מומלצת לאבטחה, מומלץ מאוד לאכוף אימות על ידי הגדרת tools-list.security בקטע x-google-api-management.mcp. אפשר לתת שם לסכימת JWT או לסכימת מפתח API.

בדוגמה הבאה נדרש JWT:

x-google-api-management:
  mcp:
    tools-list:
      security:
        myJWT: []

בדוגמה הבאה נדרש מפתח API. הלקוחות צריכים לשלוח את המפתח בכותרת ה-HTTP ‏x-api-key. המערכת של tools/list לא קוראת מפתחות API מפרמטרים של שאילתות. בקשה בלי מפתח תקין מקבלת שגיאת JSON-RPC ולא מקבלת רשימת כלים. במאמר שימוש במפתחות API מוסבר איך ליצור מפתח API.

x-google-api-management:
  mcp:
    tools-list:
      security:
        api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      name: x-api-key
      in: header

4. יצירה ופריסה של הגדרת ה-API

יוצרים הגדרת API מהמפרט עם ההערות ופורסים אותה בשער באמצעות התהליך הרגיל. פרטים נוספים זמינים במאמר פריסת API לשער. כדי לשנות את הכלים בהמשך, עיינו בקטע עדכון כלי MCP חשופים.

5. אימות התמיכה ב-MCP

אחרי הפריסה, אתם יכולים לוודא שהשער מטפל בבקשות MCP.

לחיצת יד

שולחים בקשת אתחול כדי לקבוע את גרסת הפרוטוקול ואת היכולות:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -d '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": {"name": "demo-client", "version": "1.0.0"}
  }
}'

אישור לחיצת יד

מאשרים את האתחול. השער מגיב עם HTTP 202 Accepted:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "method": "notifications/initialized"}'

הכלים שלנו

להציג את הכלים הזמינים. אם הגדרתם את tools-list.security, הוסיפו את פרטי הכניסה התואמים, כמו כותרת Authorization: Bearer ל-JWT או כותרת x-api-key למפתח API:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

איך הארגומנטים ממופים לבקשת ה-REST

הארגומנטים שמועברים לכלי ממופים לבקשת ה-REST הבסיסית על סמך מפרט OpenAPI:

פרמטרים של נתיב ושאילתה: הופכים למאפיינים ברמה העליונה באובייקט arguments, עם מפתח לפי שמות הפרמטרים שלהם ב-OpenAPI.
גוף הבקשה: מקונן מתחת למאפיין יחיד בשם body. לדוגמה, כדי ליצור משאב, מעבירים את {"body": {"fieldName": "value"}}.
כותרות: הופכות גם הן למאפיינים ברמה העליונה. השער מוסיף אותם ככותרות HTTP רגילות בקריאה לקצה העורפי.

אי אפשר להבחין בין בקשת הקצה העורפי שעברה המרת קידוד לבין בקשת REST ישירה לשירות לקצה העורפי. שירותים לקצה העורפי לא יכולים להבחין באופן פרוגרמטי בין קריאת REST ישירה לבין קריאה שעברה המרת קידוד מ-MCP.

הפעלת כלי

להפעיל כלי ספציפי. אם פעולת ה-REST הבסיסית דורשת אסימוני אימות, צריך לכלול אותם:

curl -X POST https://my-gateway-12345.uc.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "delete_shelf",
    "arguments": {"shelf": "sci-fi"}
  }
}'

עדכון כלי ה-MCP החשופים

הגדרות ה-API ב-API Gateway לא ניתנות לשינוי, ולכן אי אפשר לשנות את הגדרת ה-API בהגדרת API קיימת. כתוצאה מכך, התגובה של tools/list היא סטטית לכל הגדרת API שנפרסה.

כדי להוסיף, להסיר, לשנות את השם או לעדכן את כלי ה-MCP החשופים או את הגדרות האבטחה של tools/list, צריך ליצור הגדרת API חדשה ולפרוס אותה בשער הגישה:

מעדכנים את מפרט OpenAPI 3.x, כולל פעולות, ערכי operationId, סיכומים, פרמטרים והתוספים x-google-api-management.mcp ו-x-google-mcp-tool.
יוצרים הגדרת API חדשה עם מזהה הגדרת API חדש:
```
gcloud api-gateway api-configs create NEW_CONFIG_ID \
    --api=API_ID \
    --openapi-spec=API_DEFINITION \
    --project=PROJECT_ID \
    --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫NEW_CONFIG_ID: מזהה חדש להגדרת ה-API המעודכנת
- ‫API_ID: המזהה של API Gateway API
- ‫API_DEFINITION: הנתיב למפרט המעודכן של OpenAPI 3.x
- ‫PROJECT_ID: מזהה הפרויקט ב- Google Cloud
- SERVICE_ACCOUNT_EMAIL: כתובת האימייל של חשבון השירות שמשמש לחתימה על אסימונים לקצוות עורפיים עם אימות מוגדר. אם אף אחד מה-backend לא דורש אימות, אפשר להשמיט את הדגל הזה.
מידע נוסף זמין במאמר יצירת הגדרת API.
מעדכנים כל שער שמשרת את ה-API כך שישתמש בהגדרת ה-API החדשה:
```
gcloud api-gateway gateways update GATEWAY_ID \
    --api=API_ID \
    --api-config=NEW_CONFIG_ID \
    --location=GCP_REGION \
    --project=PROJECT_ID
```
מחליפים את מה שכתוב בשדות הבאים:
- ‫GATEWAY_ID: מזהה השער שרוצים לעדכן
- ‫GCP_REGION: האזור שבו נפרס שער הגישה
מידע נוסף זמין במאמר עדכון שער.
כדי לבדוק את ערכת הכלים המעודכנת, אפשר לקרוא לפונקציה tools/list. דוגמה לבקשה מופיעה בקטע חיפוש כלים.
אחרי שאין שערים שמשתמשים בהגדרת ה-API הקודמת, מוחקים את הגדרת ה-API שהוחלפה:
```
gcloud api-gateway api-configs delete OLD_CONFIG_ID \
    --api=API_ID \
    --project=PROJECT_ID
```
מחליפים את OLD_CONFIG_ID במזהה של הגדרת ה-API שהוחלפה. אל תמחקו הגדרת API כל עוד שער כלשהו עדיין משתמש בה. אם בהגדרת ה-API החדשה משנים את השם של מדדי המכסות או מסירים אותם, שערים שעדיין משתמשים בהגדרת API ישנה יותר יכולים להחזיר שגיאות HTTP 500 עד שהם יעודכנו (ראו המכסות חלות על כל ה-API). מידע נוסף זמין במאמר מחיקת הגדרת API.

כשמעדכנים את כלי ה-MCP, חשוב לזכור את הדברים הבאים לגבי ההשקה וההתנהגות של הלקוח:

השקה ללא זמן השבתה: עדכון השערים ב-API Gateway מתבצע ללא זמן השבתה. בזמן שהגדרת ה-API החדשה מופצת, יכול להיות שחלק מהבקשות יגיעו לזמן קצר להגדרת ה-API הקודמת. אם ה-API שלכם פרוס בכמה שערים או אזורים, צריך לעדכן כל שער בנפרד.
מטמונים של כלי לקוח: מכיוון ש-API Gateway מציג את MCP באמצעות תעבורת HTTP ללא שמירת מצב, השער לא פולט התראות notifications/tools/list_changed. אחרי שהשער מתעדכן, לקוחות MCP ששומרים במטמון הגדרות של כלים צריכים לקרוא שוב ל-tools/list כדי לגלות את הכלים המעודכנים.
מגבלות על הגדרות ה-API: כל API מוגבל ל-100 הגדרות API, לכן צריך למחוק הגדרות API שהוחלפו אחרי שמעדכנים את השערים. צריך ליצור הגדרות API אחת אחרי השנייה. אם תתחילו ליצור הגדרת API שנייה לאותו API לפני שהראשונה תסתיים, יכול להיות שלא תוכלו להשתמש באחת מהן או בשתיהן בשער. מידע נוסף זמין במאמר מכסות ומגבלות.

ניראות (observability)

בקשות MCP מניבות מדדים ויומנים סטנדרטיים של API Gateway. כדי להבדיל בין תנועת MCP לתנועת REST רגילה, אפשר לבדוק את נתיב הבקשה (בדרך כלל מסתיים ב-/mcp) או להגדיר מדדים מותאמים אישית.

פתרון בעיות שקשורות לכשלים ב-MCP

פרוטוקול MCP מבחין בין כשלים בהעברה לבין כשלים בפרוטוקול. השער מחזיר HTTP 200 עם אובייקט שגיאה של JSON-RPC לשגיאות בפרוטוקול ובאפליקציה, כי תגובות שהן לא 200 יכולות לגרום להרבה לקוחות MCP להיכשל בשכבת התעבורה.

בטבלה הבאה מתוארים תסמינים נפוצים ופתרונות:

תיאור הבעיה	קוד JSON-RPC	סטטוס HTTP	משמעות ופתרון אופייני
השיטה אסורה	לא רלוונטי	`405`	בקשה שאינה בקשת POST הגיעה אל `/mcp`. יש תמיכה רק ב-HTTP `POST`.
שגיאה בניתוח JSON	`-32700`	`400`	גוף הבקשה הוא לא JSON תקין.
שיטה או מזהה חסרים או לא תקינים	`-32600`	`200`	הגוף הוא JSON תקין אבל לא בקשת JSON-RPC תקינה. צריך לוודא שמילאת את שדות החובה (`jsonrpc`, `method`, `id`).
אין תמיכה בשיטה	`-32601`	`200`	השיטה לא נכללת בהיקף הנתמך (למשל, `ping`).
גרסת הפרוטוקול לא נתמכת	`-32602`	`200`	השדה `protocolVersion` מציין גרסה שהשער לא תומך בה.
חסרה גרסת פרוטוקול	`-32602`	`200`	הפרמטרים של `initialize` משמיטים את `protocolVersion` או שהערך הוא לא מחרוזת.
כלי לא ידוע	`-32602`	`200`	שם הכלי לא נמצא בהגדרת ה-API שנפרס. מרעננים את המטמון של כלי הלקוח, או מעיינים בקטע עדכון כלי MCP חשופים.
ארגומנטים לא תקינים של הכלי	`-32602`	`200`	הארגומנטים חסרים או לא תקינים. צריך לוודא שהמפתח `body` מקונן.
הפוסט גדול מדי	`-32000`	`200`	המטען הייעודי (payload) של התגובה חרג ממגבלות הגודל.
גוף ההעברה גדול מדי	לא רלוונטי	`413`	גוף בקשת ה-HTTP הגולמית חרג ממגבלות ההעברה של השער.
שגיאה בחיבור לשרת	`-32000`	`200`	תגובת קצה עורפי שלא ניתן לנתח. בודקים את היומנים.
אין הרשאה / אסור	לא רלוונטי	`401` / `403`	האימות נכשל. התשובה מכילה כותרת `WWW-Authenticate` שמפנה למטא-נתונים של המשאב המוגן.

שגיאות באפליקציית הקצה העורפי בדרך כלל מופיעות כתגובת JSON-RPC תקינה (HTTP 200) עם result.isError: true שמכיל את גוף השגיאה בקצה העורפי.