הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.
לצפייה במאמרי העזרה של
Apigee Edge.
בדף הזה מוסבר איך להשתמש בשרת proxy של Apigee Discovery כדי להפוך את ממשקי ה-API שלכם לזמינים ללקוחות של Model Context Protocol (MCP) באפליקציות מבוססות-סוכנים ככלי MCP.
לפני שמתחילים
לפני שמתחילים, צריך לבצע את המשימות הבאות:
- נכנסים לחשבון Google Cloud . אנחנו ממליצים למשתמשים חדשים ב- Google Cloud ליצור חשבון כדי שיוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
- מוודאים שהוקצה לכם ארגון ב-Apigee. פרוקסי הגילוי של MCP זמין לארגונים עם מינוי, עם תשלום לפי שימוש ועם הערכה, ולגרסה
1.17.0ואילך של Apigee Hybrid. מידע נוסף זמין במאמר מבוא להקצאת הרשאות ידנית. - רק ב-Apigee Hybrid: ודאו שהשלמתם את השלבים החד-פעמיים להפעלת האשכול, שמתוארים במאמר הפעלת MCP ב-Apigee Hybrid. כדי לעשות את זה, צריך להגדיר את
enableMcpServer: trueכמפתח ברמה העליונה ב-overrides.yamlולהריץ אתhelm upgradeמול התרשימים שלapigee-operatorו-apigee-org. - מוודאים שיש לכם מכונה של Apigee API hub שהוקצתה בפרויקט Google Cloud . מידע נוסף זמין במאמר הקצאת API Hub במסוף Google Cloud . כדי לוודא שהשירות API Hub מופעל, אתם יכולים לבדוק את הדף Hub במסוף Google Cloud .
- מוודאים שמכונה של Apigee מצורפת לשירות API Hub. אי אפשר להשתמש בשרת ה-proxy של MCP Discovery עם מופעי פלאגין של Apigee Edge for Public Cloud או Apigee Edge for Private Cloud ב-API Hub. מידע נוסף זמין במאמר צירוף פרויקט של סביבת זמן ריצה. אפשר לבדוק את סטטוס השיוך של פרויקט זמן הריצה בכרטיסייה Project associations בדף Settings במסוף Google Cloud .
התפקידים הנדרשים
כדי לקבל את ההרשאות שנדרשות ליצירה ולפריסה של שרת proxy לזיהוי MCP, בקשו מהאדמין להקצות לכם את התפקיד אדמין של Apigee (roles/apigee.admin) ב-IAM בחשבון השירות שבו אתם משתמשים כדי לפרוס שרתי proxy של Apigee.
כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.
יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.
הפעלת ממשקי ה-API
מפעילים את Apigee API, אם הוא עדיין לא מופעל.
התפקידים שנדרשים כדי להפעיל ממשקי API
כדי להפעיל ממשקי API, צריך את ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד "בעלים" (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד "אדמין בממשק 'שימוש בשירות'" (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים
הגדרה של משתני סביבה
בפרויקט ב- Google Cloud שמכיל את המכונה של Apigee, משתמשים בפקודה הבאה כדי להגדיר משתני סביבה:
export PROJECT_ID=PROJECT_IDexport REGION=REGIONexport RUNTIME_HOSTNAME=RUNTIME_HOSTNAME
כאשר:
-
PROJECT_IDהוא מזהה הפרויקט עם המכונה של Apigee. -
REGIONהוא Google Cloud האזור של המכונה של Apigee. ב-Apigee Hybrid, זה האזור שבו נמצא האשכול. -
RUNTIME_HOSTNAMEהוא שם המארח של סביבת זמן הריצה של Apigee. ב-Apigee Hybrid, זהו שם המארח שרשום בקבוצת הסביבות של Apigee ומוצג על ידי שער הכניסה של Apigee (לדוגמה,api.example.com).
כדי לוודא שמשתני הסביבה מוגדרים בצורה נכונה, מריצים את הפקודה הבאה ובודקים את הפלט:
echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME
הגדרת הפרויקט
מגדירים את הפרויקט ב- Google Cloud בסביבת הפיתוח:
gcloud auth logingcloud config set project $PROJECT_ID
סקירה כללית
כדי לחשוף את ממשקי ה-API שלכם ככלי MCP באמצעות Apigee, אתם צריכים ליצור ולפרוס שרת proxy חדש של Apigee באמצעות התבנית MCP Discovery Proxy. אחרי שפורסים את שרת ה-proxy, אפשר ליצור מוצר API כדי לאגד את פעולות ה-API של MCP בשרת ה-proxy למוצר API. כמוצר API, לקוחות MCP יכולים לגלות את הפעולות והכלים של ה-API שלכם באמצעות שילוב ב-API Hub.
בקטעים הבאים מוסבר איך ליצור ולפרוס שרת פרוקסי ל-MCP Discovery, ליצור מוצר API ולראות את הכלים הזמינים:
- יוצרים מפרט OpenAPI 3.0.x שמתאר את פעולות ה-API.
- יצירת שרת proxy ל-MCP Discovery.
- (אופציונלי) מוסיפים מדיניות אבטחה ל-MCP Discovery Proxy.
- פורסים את שרת ה-proxy של MCP Discovery.
- (אופציונלי) מפעילים את שרת ה-MCP.
- רשימת הכלים הזמינים
יוצרים מפרט של OpenAPI 3.0.x שמתאר את פעולות ה-API
לפני שיוצרים ופורסים את שרת ה-proxy לזיהוי MCP, צריך ליצור מפרט OpenAPI 3.0.x שמתאר את פעולות ה-API שרוצים לחשוף ככלים של MCP. MCP ב-Apigee תומך בגרסאות הבאות של OpenAPI:
- 3.0.0
- 3.0.1
- 3.0.2
- 3.0.3
במדריך הזה נשתמש במפרט לדוגמה של OpenAPI 3.0.x עם שלוש פעולות API:
-
GET /artists: מחזירה רשימה של אומנים. POST /artists: מאפשר למשתמש לפרסם אומן חדש.-
GET /artists/{username}: קבלת מידע על אומן לפי שם המשתמש הייחודי שלו.
כדי ליצור את המפרט של OpenAPI 3.0.x:
- יוצרים קובץ
mcp-quickstart-openapi.yamlחדש בספרייהoasשל חבילת ה-proxy ל-API. - מוסיפים את התוכן הבא לקובץ:
# mcp-quickstart-openapi.yaml --- openapi: 3.0.3 info: title: Cymbal Group Products API description: This is the official API for managing the artists for Cymbal Group Products. version: 1.0.0 servers: - url: https://cymbal.products.com description: Cymbal Group Production Server - url: https://internal.products.com description: Cymbal Group internal Server paths: /artists: get: description: Returns a list of artists operationId: listArtists parameters: - name: limit in: query description: Limits the number of items on a page schema: type: integer - name: offset in: query description: Specifies the page number of the artists to be displayed schema: type: integer responses: "200": description: An array of artists content: application/json: schema: type: array items: $ref: "#/components/schemas/Artist" post: summary: Create a new artist operationId: createArtist tags: - artists requestBody: description: The artist to create. required: true content: application/json: schema: $ref: "#/components/schemas/Artist" responses: "201": description: The newly created artist profile content: application/json: schema: $ref: "#/components/schemas/Artist" "400": description: Invalid username supplied /artists/{username}: get: summary: Info for a specific artist operationId: showArtistByUsername tags: - artists parameters: - name: username in: path required: true description: The username of the artist to retrieve schema: type: string responses: "200": description: Expected response to a valid request content: application/json: schema: $ref: "#/components/schemas/Artist" "404": description: Artist not found components: securitySchemes: bearerAuth: type: http scheme: bearer oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: /oauth/authorize tokenUrl: /oauth/token scopes: artists.read: Grants read access artists.write: Grants write access schemas: Artist: type: object required: - id properties: id: type: string format: uuid description: Unique identifier for the artist
הדרישה להתאמה של שם המארח
חשוב מאוד שהערך של שם המארח בשדה servers.url של מפרט OpenAPI יהיה התאמה מדויקת לשם המארח של קבוצת הסביבות של Apigee שבה פרוס ה-MCP Discovery Proxy.
ההתאמה הזו נדרשת כדי שהקריאות tools/list ו-tools/call יפעלו בצורה תקינה.
בטבלה הבאה מוצגת הגדרת שם המארח במפרט OpenAPI והגדרת שם המארח התואמת בקבוצת הסביבות של Apigee:
| רכיב | ההגדרה הנדרשת | ערך לדוגמה | פרטים תומכים |
|---|---|---|---|
| קבוצת סביבות ב-Apigee | שמות המארחים חייבים להיות מוגדרים בקבוצת הסביבות. | cymbal.products.com, internal.products.com |
קבוצות של סביבות מאפשרות ניתוב לקבוצה של סביבות באמצעות שם מארח. |
| מפרט OpenAPI | הערך של השדה servers.url במפרט של OpenAPI חייב להיות התאמה מדויקת לשם המארח של קבוצת הסביבות של סביבת Apigee שבה פרוס שרת ה-proxy של MCP Discovery. |
https://cymbal.products.com |
אם שם המארח של servers.url לא תואם לשם המארח של קבוצת הסביבות שתואמת לסביבת Apigee שבה פרוס שרת ה-proxy של MCP Discovery, תופיע שגיאה בזמן פריסת שרת ה-proxy. |
יצירת שרת פרוקסי ל-MCP Discovery
אחרי שיש לכם מפרט OpenAPI 3.0.x שמגדיר את פעולות ה-API, אתם יכולים ליצור שרת proxy חדש ל-API באמצעות התבנית MCP Discovery Proxy.
כדי ליצור שרת פרוקסי ל-MCP Discovery:
- נכנסים לדף API proxies במסוף Google Cloud .
- לוחצים על + Create כדי לפתוח את החלונית Create proxy ל-API.
- בתיבה Proxy template, בוחרים באפשרות MCP Discovery Proxy.
- בקטע פרטי שרת ה-proxy, מזינים את הפרטים הבאים:
- שם שרת ה-Proxy: שם לשרת ה-Proxy.
- תיאור (אופציונלי): תיאור של שרת ה-proxy. לדוגמה,
My first MCP Discovery Proxy.
- לוחצים על הבא.
- בקטע OpenAPI specs, משתמשים בדפדפן הקבצים כדי לבחור את קובץ OpenAPI 3.0.x שיצרתם בשלב הקודם.
- לוחצים על הבא.
- בקטע Deploy (optional), אתם יכולים לדלג על פריסת שרת ה-proxy בשלב הזה. לוחצים על Next.
- לוחצים על יצירה.
כדי לראות את נקודות הקצה של היעד והשרת של שרת ה-proxy, לוחצים על View בעמודה Endpoint summary בטבלה Revisions. בסיכום נקודת הקצה של הגרסה של גרסת ה-proxy שנבחרה מוצג המידע הבא:
- Proxy endpoints: בדוגמה הזו, מוצגת נקודת הקצה של שרת ה-proxy
defaultעם נתיב בסיס של/mcp. אם מוסיפים לשרת ה-proxy עוד שמות מארחים או קבוצות סביבה, גם הם יופיעו כאן. - נקודות קצה (endpoint) לטירגוט: בדוגמה הזו, החיבור לטירגוט של
defaultמוגדר ל-ORG_NAME.mcp.apigee.internal, כאשרORG_NAMEהוא השם של הארגון שלכם ב-Apigee. היעדmcp.apigee.internalנתמך גם לצורך תאימות לדורות קודמים.
(אופציונלי) הוספת מדיניות אבטחה ל-MCP Discovery Proxy
לפני שפורסים את שרת ה-proxy של MCP Discovery, אפשר להוסיף מדיניות אבטחה כדי לאכוף את דרישות האבטחה. מומלץ לאבטח את הגישה ל-MCP Discovery Proxy באמצעות אסימוני OAuth או מפתח API.
בקטע הזה מוסבר איך להוסיף מדיניות OAuthV2 ל-MCP Discovery Proxy. כך אפשר לוודא שכל הבקשות ל-MCP Discovery Proxy מאומתות ומורשות. אם אתם רוצים להשתמש במפתח API, תוכלו לקרוא את השלבים המומלצים במאמר אבטחת API באמצעות דרישה למפתחות API.
כדי להגדיר אימות טוקן, צריך להוסיף מדיניות OAuthV2 עם הפעולה VerifyAccessToken ממש בתחילת התהליך של ה-proxy ל-API (ההתחלה של ProxyEndpoint Preflow). אם הם ממוקמים שם, טוקני הגישה מאומתים לפני כל עיבוד אחר, ואם טוקן נדחה, Apigee מפסיקה את העיבוד ומחזירה שגיאה ללקוח.
כדי להוסיף את המדיניות VerifyAccessToken:
- בדף הפרטים של שרת ה-proxy, לוחצים על הכרטיסייה Develop.
- בקטע Proxy endpoints, לוחצים על default ואז על PreFlow.
בעורך של תהליך ה-proxy, לוחצים על Add policy step.

- בתיבת הדו-שיח Add policy step, בוחרים באפשרות Create new policy.
- ברשימת כללי המדיניות, בקטע Security, בוחרים באפשרות OAuth v2.0.
- אם רוצים, משנים את שם המדיניות ואת השם המוצג. לדוגמה, כדי לשפר את הקריאוּת, אפשר לשנות את השם המוצג ואת Name ל-VerifyAccessToken.
- לוחצים על הוספה.
פריסת שרת ה-proxy לגילוי MCP
כדי לפרוס את שרת ה-Proxy לזיהוי MCP:
- לוחצים על Deploy כדי לפתוח את החלונית Deploy proxy ל-API.
- השדה Revision צריך להיות מוגדר ל-1. אם לא, לוחצים על 1 כדי לבחור אותה.
- ברשימה Environment, בוחרים את הסביבה שבה רוצים לפרוס את שרת ה-proxy. הסביבה חייבת להיות סביבה מקיפה.
- מזינים את חשבון השירות שיצרתם בשלב קודם.
- לוחצים על Deploy.
כשלוחצים על Deploy, המערכת של Apigee מתחילה לפרוס את שרת ה-proxy ולהקצות רכיבים במורד הזרם. בזמן הזה, שיכול להימשך כמה דקות, בממשק המשתמש יוצג הסטטוס Provisioning (הקצאה ידנית) של הפריסה.
בסיום התהליך, הסטטוס משתנה ל-Deployed והשרת proxy מוכן לטפל בתנועה.
אחרי שפורסים את ה-proxy, מוודאים שהערך של שם המארח בשדה servers.url של מפרט OpenAPI תואם בדיוק לשם המארח של קבוצת הסביבות של סביבת Apigee שבה נפרס ה-MCP Discovery Proxy.
איך למצוא כלי MCP ב-API Hub
אחרי שפורסים את שרת ה-Proxy של MCP Discovery, פעולות ה-API שלו נשלחות באופן אוטומטי אל API Hub וזמינות ככלי MCP.
כדי לראות את כלי ה-MCP ב-API Hub:
- במסוף Google Cloud , נכנסים לדף API Hub > APIs.
- לוחצים על סינון ובוחרים באפשרות סגנון > MCP, ואז לוחצים על אישור.
- שרת ה-proxy של MCP שפרסתם אמור להופיע ברשימה. צינור עיבוד הנתונים של API Hub ממפה באופן אוטומטי את הנתיבים שמוגדרים במפרט OpenAPI לכלי MCP ספציפיים שמופיעים ב-Hub.
מפתחים בארגון יכולים עכשיו להשתמש במסננים או בחיפוש סמנטי ב-API Hub כדי למצוא כלים רלוונטיים של MCP באמצעות שאילתות בשפה טבעית.
הפעלת שרת ה-MCP
בשלב הזה, שולחים בקשה לנקודת הקצה של ה-MCP כדי להפעיל את שרת ה-MCP ולוודא שהוא פועל כמו שצריך.
כדי להפעיל ולבדוק את שרת ה-MCP, שולחים את הבקשה הבאה לנקודת הקצה של ה-MCP:
curl -X POST "https://MCP_ENDPOINT_URL/mcp" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "MCP_PROTOCOL_VERSION" } }' \ -H "Authorization: Bearer TOKEN"
מחליפים את מה שכתוב בשדות הבאים:
-
MCP_ENDPOINT_URL: ה-URI הבסיסי של נקודת הקצה של ה-MCP. לדוגמה,cymbal.products.com. -
MCP_PROTOCOL_VERSION: גרסת פרוטוקול ה-MCP. לדוגמה,2025-11-25. מידע נוסף זמין בקטע Version Negotiation במפרט של MCP. - (אופציונלי)
TOKEN: טוקן גישה מסוג OAuth 2.0
תגובה מוצלחת נראית בערך כך:
{
"id":1,
"jsonrpc":"2.0",
"result":
{
"capabilities":
{
"tools":
{
"listChanged":false
}
},
"protocolVersion":"2025-11-25",
"serverInfo":
{
"name":"cymbal.products.com",
"version":"1.0.0"
}
}
}רשימת כלי ה-MCP הזמינים
בשלב הזה, אתם שולחים בקשה ל-method tools/list כדי לאשר את רשימת הכלים שזמינים בנקודת הקצה של ה-MCP.
שולחים בקשה ל-method tools/list של שרת ה-proxy של Apigee:
curl -X POST "https://MCP_ENDPOINT_URL/mcp" \ -H "Content-Type: application/json" \ -H "MCP-Protocol-Version: MCP_PROTOCOL_VERSION" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }' \ -H "Authorization: Bearer TOKEN"
מחליפים את מה שכתוב בשדות הבאים:
-
MCP_ENDPOINT_URL: ה-URI הבסיסי של נקודת הקצה של ה-MCP. לדוגמה,cymbal.products.com. -
MCP_PROTOCOL_VERSION: גרסת פרוטוקול ה-MCP. לדוגמה,2025-11-25. מידע נוסף זמין בקטע כותרת של גרסת הפרוטוקול במפרט של MCP. - (אופציונלי)
TOKEN: טוקן גישה מסוג OAuth 2.0
ה-method מחזירה את כל הכלים שנקודת הקצה של ה-MCP תומכת בהם. תגובה מוצלחת נראית בערך כך:
{ "id": 1, "jsonrpc": "2.0", "result": { "tools": [ { "description": "Returns a list of artists", "inputSchema": { "properties": { "id": { "description": "Unique identifier for the artist", "format": "uuid", "type": "string" } }, "type": "object" }, "name": "listArtists" }, { "description": "Create a new artist", "inputSchema": { "properties": { "id": { "description": "Unique identifier for the artist", "format": "uuid", "type": "string" } }, "type": "object" }, "name": "createArtist" }, { "description": "Info for a specific artist", "inputSchema": { "properties": { "id": { "description": "Unique identifier for the artist", "format": "uuid", "type": "string" } }, "type": "object" }, "name": "showArtistByUsername" } ] } }
אחרי שנקודת הקצה אותחלה, מפתחים וסוכנים שמשתמשים במוצר ה-API שלכם יכולים לגלות את כלי ה-MCP.
מעקב וניתוח נתונים
אתם יכולים לעקוב אחרי התנועה ב-MCP ולראות מדדים ברמת הכלי באמצעות Apigee Analytics.
ב-Apigee Analytics אתם יכולים לסנן מדדים כדי להבחין בין תנועת API רגילה לבין תנועה ספציפית ל-MCP, ולראות את נפח השימוש בבקשות tools/list לעומת בקשות tools/call. מידע נוסף זמין במאמר מעקב וניתוח של תנועת MCP ב-Apigee.
המאמרים הבאים
- פתרון בעיות בפריסות של MCP ב-Apigee
- מעקב וניתוח של תנועת הנתונים של MCP ב-Apigee.
- ב-Apigee Hybrid: קוראים את תהליך ההפעלה וההגדרה בצד האשכול במאמר הפעלת MCP ב-Apigee Hybrid.