תחילת העבודה עם Apigee ו-MCP

הדף הזה מתייחס ל-Apigee, אבל לא ל-Apigee Hybrid.

לעיון במסמכי התיעוד של Apigee Edge

בדף הזה נסביר איך להשתמש ב-Apigee Discovery proxy כדי להפוך את ממשקי ה-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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

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 the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

1. מוודאים שיש לכם הקצאת משאבים לארגון Apigee. הפרוקסי של MCP Discovery זמין לארגונים עם מינוי, לארגונים עם תשלום לפי שימוש ולארגונים עם חשבון לצורך הערכה. מידע נוסף זמין במאמר מבוא להקצאת הרשאות.
2. מוודאים שיש לכם מופע של Apigee API hub שהוקצה לכם ב Google Cloud פרויקט. מידע נוסף זמין במאמר בנושא הקצאת API Hub במסוף. Google Cloud כדי לוודא ששירות ה-API Hub מופעל, אפשר לעיין בדף Hub במסוף Google Cloud .

   כניסה ל-API Hub

3. מוודאים שמופע של Apigee מצורף לשירות של מרכז ה-API. אי אפשר להשתמש ב-MCP Discovery proxy עם מופעי פלאגין של Apigee Edge לענן ציבורי או Apigee Edge לענן פרטי ב-API Hub. מידע נוסף זמין במאמר צירוף פרויקט של זמן ריצה. אפשר לבדוק את הסטטוס של צירוף פרויקט בזמן ריצה בכרטיסייה Project associations (שיוכים לפרויקט) בדף Settings (הגדרות) במסוף Google Cloud .

   כניסה ל-API Hub

התפקידים הנדרשים

כדי לקבל את ההרשאות שדרושות ליצירה ולפריסה של MCP Discovery Proxy, צריך לבקש מהאדמין להקצות לכם ב-IAM את התפקיד אדמין של Apigee (roles/apigee.admin) בחשבון השירות שבו אתם משתמשים כדי לפרוס פרוקסי של Apigee. כדי לקרוא הסבר על מתן תפקידים, ראו איך מנהלים את הגישה ברמת הפרויקט, התיקייה והארגון.

יכול להיות שאפשר לקבל את ההרשאות הנדרשות גם באמצעות תפקידים בהתאמה אישית או תפקידים מוגדרים מראש.

הפעלת ממשקי ה-API

מפעילים את Apigee API.

תפקידים שנדרשים להפעלת ממשקי API

כדי להפעיל ממשקי API, צריך את תפקיד ה-IAM 'אדמין של Service Usage' (roles/serviceusage.serviceUsageAdmin), שכולל את ההרשאה serviceusage.services.enable. איך מקצים תפקידים

להפעלת ה-API

הגדרה של משתני סביבה

בפרויקט Google Cloud שמכיל את מופע Apigee, משתמשים בפקודה הבאה כדי להגדיר משתני סביבה:

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export RUNTIME_HOSTNAME=RUNTIME_HOSTNAME

כאשר:

• ‫PROJECT_ID הוא מזהה הפרויקט עם מופע Apigee.
• ‫REGION הוא האזור של מופע Apigee. Google Cloud
• ‫RUNTIME_HOSTNAME הוא שם המארח של זמן הריצה של Apigee.

כדי לוודא שמשתני הסביבה מוגדרים בצורה נכונה, מריצים את הפקודה הבאה ובודקים את הפלט:

echo $PROJECT_ID $REGION $RUNTIME_HOSTNAME

הגדרת הפרויקט

מגדירים את Google Cloud הפרויקט בסביבת הפיתוח:

    gcloud auth login
    gcloud config set project $PROJECT_ID

סקירה כללית

כדי לחשוף את ממשקי ה-API שלכם ככלים של MCP באמצעות Apigee, אתם יוצרים ופורסים שרת proxy חדש של Apigee באמצעות התבנית MCP Discovery Proxy. אחרי פריסת ה-proxy, אתם יכולים ליצור מוצר API כדי לאגד את פעולות ה-API של MCP ב-proxy למוצר API. בתור מוצר API, לקוחות MCP יכולים לגלות את פעולות ה-API או הכלים שלכם באמצעות שילוב ב-API Hub.

בקטעים הבאים מתוארים השלבים ליצירה ולפריסה של שרת proxy של MCP Discovery, ליצירה של מוצר API ולרשימה של כלים זמינים:

1. יוצרים מפרט OpenAPI 3.0.x שמתאר את פעולות ה-API.
2. יוצרים שרת proxy של MCP Discovery.
3. (אופציונלי) מוסיפים מדיניות אבטחה לשרת ה-proxy של MCP Discovery.
4. פורסים את שרת ה-proxy של MCP Discovery.
5. (אופציונלי) מאתחלים את שרת ה-MCP.
6. רשימת הכלים הזמינים.

יצירת מפרט OpenAPI 3.0.x שמתאר את פעולות ה-API

לפני שיוצרים ומפעילים את שרת ה-proxy של MCP Discovery, צריך ליצור מפרט 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:

1. יוצרים קובץ mcp-quickstart-openapi.yaml חדש בספרייה oas של חבילת ה-proxy ל-API.
2. מוסיפים את התוכן הבא לקובץ:

   # 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 נפרס. ההתאמה הזו נדרשת כדי שהקריאות tools/list ו-tools/call יפעלו בצורה תקינה.

בטבלה הבאה מוצגת הגדרת שם המארח במפרט OpenAPI והגדרת שם המארח התואמת בקבוצת הסביבות של Apigee:

רכיב	הגדרה נדרשת	ערך לדוגמה	פרטים תומכים
קבוצת סביבות ב-Apigee	צריך להגדיר את שמות המארחים בקבוצת הסביבות.	cymbal.products.com, internal.products.com	קבוצות סביבות מאפשרות ניתוב לקבוצת סביבות באמצעות שם מארח.
מפרט OpenAPI	הערך בשדה servers.url של מפרט OpenAPI חייב להיות זהה לשם המארח של קבוצת הסביבות בסביבת Apigee שבה פרוקסי הגילוי של MCP נפרס.	https://cymbal.products.com	אם שם המארח servers.url לא תואם לשם המארח של קבוצת הסביבות שמתאימה לסביבת Apigee שבה מתבצעת הפריסה של שרת ה-proxy של MCP Discovery, תוצג שגיאה כשמנסים לפרוס את שרת ה-proxy.

יצירת שרת proxy של MCP Discovery

אחרי שיש לכם מפרט OpenAPI 3.0.x שמגדיר את פעולות ה-API, אתם יכולים ליצור proxy ל-API חדש באמצעות התבנית MCP Discovery Proxy.

כדי ליצור שרת proxy של MCP Discovery:

1. נכנסים לדף API proxies במסוף Google Cloud .

   מעבר לשרתי proxy ל-API

2. לוחצים על + Create כדי לפתוח את החלונית Create proxy ל-API.
3. בתיבה תבנית proxy, בוחרים באפשרות MCP Discovery Proxy.
4. בקטע פרטי השרת הפרוקסי, מזינים את הפרטים הבאים:
   • שם שרת ה-Proxy: שם לשרת ה-Proxy.
   • תיאור (אופציונלי): תיאור של השרת הפרוקסי. לדוגמה, My first MCP Discovery Proxy.
5. לוחצים על הבא.
6. בקטע OpenAPI specs (מפרטי OpenAPI), משתמשים במנהל הקבצים והתיקיות כדי לבחור את קובץ OpenAPI 3.0.x שיצרתם בשלב הקודם.
7. לוחצים על הבא.
8. בקטע Deploy (optional), אפשר לדלג על פריסת ה-proxy בשלב הזה. לוחצים על Next.
9. לוחצים על יצירה.
   הערה: יכול להיות שיעברו עד עשר דקות עד שהפרוקסי ייווצר. כשהפעולה תסתיים, תועברו לדף הפרטים סיכום ה-Proxy, שבו תוכלו לראות את ה-Proxy של MCP Discovery.

כדי לראות את נקודות הקצה של השרת והיעד של ה-proxy, לוחצים על View בעמודה Endpoint summary בטבלה Revisions. סיכום נקודת הקצה של הגרסה של הגרסה של ה-proxy שבחרתם מציג את המידע הבא:

• נקודות קצה של שרת proxy: בדוגמה הזו מוצגת נקודת הקצה של שרת ה-proxy‏ default עם נתיב בסיסי של /mcp. אם נוספים לשרת הפרוקסי שמות מארחים או קבוצות סביבות נוספים, הם יוצגו גם כאן.
• נקודות קצה של יעד: בדוגמה הזו, חיבור היעד 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:

1. בדף הפרטים של ה-proxy, לוחצים על הכרטיסייה פיתוח.
2. בקטע Proxy endpoints (נקודות קצה של שרת proxy), לוחצים על default (ברירת מחדל) ואז על PreFlow (לפני זרימת הנתונים).

3. בכלי לעריכת זרימת הנתונים של ה-proxy, לוחצים על Add policy step.

   
4. בתיבת הדו-שיח הוספת שלב מדיניות, בוחרים באפשרות יצירת מדיניות חדשה.
5. ברשימת המדיניות, בקטע אבטחה, בוחרים באפשרות OAuth v2.0.
6. אפשר לשנות את שם המדיניות ואת השם המוצג. לדוגמה, כדי לשפר את הקריאות, אפשר לשנות את השם המוצג ואת השם ל-VerifyAccessToken.
7. לוחצים על הוספה.

פריסת פרוקסי לגילוי MCP

כדי לפרוס את שרת ה-Proxy לגילוי MCP:

1. לוחצים על Deploy (פריסה) כדי לפתוח את החלונית Deploy API proxy (פריסת proxy ל-API).
2. השדה Revision צריך להיות מוגדר לערך 1. אם לא, לוחצים על 1 כדי לבחור אותה.
3. ברשימה סביבה, בוחרים את הסביבה שבה רוצים לפרוס את ה-proxy. הסביבה חייבת להיות סביבה מקיפה.
4. מזינים את חשבון השירות שיצרתם בשלב קודם.
5. לוחצים על פריסה.

כשלוחצים על Deploy, ‏ Apigee מתחיל לפרוס את ה-proxy ולספק רכיבים במורד הזרם. במהלך הזמן הזה, שיכול להימשך כמה דקות, בממשק המשתמש יוצג הסטטוס הקצאת הרשאות לפריסה.

כשהתהליך מסתיים, הסטטוס משתנה לDeployed והפרוקסי מוכן לטפל בתנועה.

אחרי פריסת ה-proxy, מוודאים שהערך של שם המארח בשדה servers.url של מפרט OpenAPI זהה בדיוק לשם המארח של קבוצת הסביבות בסביבת Apigee שבה נפרס ה-proxy של MCP Discovery.

כלים של MCP ב-API Hub

אחרי שפורסים את ה-MCP Discovery Proxy, פעולות ה-API שלו נבלעות באופן אוטומטי ב-API Hub ומוצגות ככלים של MCP.

כדי לראות את כלי ה-MCP ב-API Hub:

1. במסוף Google Cloud , נכנסים לדף API Hub > APIs.

   לדף של ממשקי API במרכז ה-API

2. לוחצים על מסנן ובוחרים באפשרות סגנון > MCP, ואז לוחצים על החלה.
3. שרת ה-proxy של ה-MCP שפרסתם אמור להופיע ברשימה. צינור ההטמעה של API Hub ממפה באופן אוטומטי את הנתיבים שהוגדרו במפרט OpenAPI לכלים נפרדים של MCP שמופיעים במרכז.

מפתחים בארגון יכולים עכשיו להשתמש במסננים או בחיפוש סמנטי ב-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 זמינים

בשלב הזה, שולחים בקשה לשיטת tools/list כדי לאשר את רשימת הכלים שזמינים בנקודת הקצה של ה-MCP.

שליחת בקשה לשיטה 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

השיטה מחזירה את כל הכלים שנקודת הקצה של 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"
      }
    ]
  }
}

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

מעקב וניתוח נתונים

אתם יכולים לעקוב אחרי התנועה של MCP ולראות מדדים ברמת הכלי באמצעות Apigee Analytics. ‫Apigee Analytics מאפשר לכם לסנן מדדים כדי להבחין בין תנועת נתונים רגילה של API לבין תנועת נתונים ספציפית ל-MCP, ולראות את נפח השימוש בבקשות tools/list לעומת בקשות tools/call. מידע נוסף זמין במאמר מעקב אחרי תעבורת נתונים של MCP וניתוח שלה ב-Apigee.

המאמרים הבאים

• פתרון בעיות בפריסות של MCP ב-Apigee
• מעקב אחרי תנועת נתונים בפרוטוקול MCP וניתוח שלה ב-Apigee