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

הדף הזה רלוונטי ל-Apigee ול-Apigee Hybrid.

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

בדף הזה מוסבר איך להשתמש ב-Apigee Discovery proxy כדי להפוך את ממשקי ה-API שלכם לזמינים ללקוחות Model Context Protocol‏ (MCP) באפליקציות מבוססות-סוכנים ככלים של MCP.

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

לפני שמתחילים, צריך לבצע את המשימות הבאות:

  1. נכנסים לחשבון Google Cloud . אם אתם משתמשים חדשים ב- Google Cloud, צרו חשבון כדי שתוכלו להעריך את הביצועים של המוצרים שלנו בתרחישים מהעולם האמיתי. לקוחות חדשים מקבלים בחינם גם קרדיט בשווי 300$ להרצה, לבדיקה ולפריסה של עומסי העבודה.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

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

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. מוודאים שיש לכם הקצאת משאבים לארגון Apigee. ה-MCP Discovery proxy זמין לארגונים עם מינוי, לארגונים עם תשלום לפי שימוש ולארגונים עם גרסת ניסיון, ולגרסה Apigee Hybrid ‏1.17.0 ואילך. מידע נוסף זמין במאמר מבוא להקצאת הרשאות.
  7. Apigee hybrid בלבד: מוודאים שהשלמתם את השלבים להפעלת האשכולות חד-פעמית שמתוארים במאמר הפעלת MCP ב-Apigee hybrid. כדי לעשות את זה, צריך להגדיר את enableMcpServer: true כמפתח ברמה העליונה ב-overrides.yaml ולהריץ את helm upgrade מול התרשימים apigee-operator ו-apigee-org.
  8. מוודאים שיש לכם מופע של Apigee API hub שהוקצה לכם ב Google Cloud פרויקט. מידע נוסף זמין במאמר בנושא הקצאת API Hub במסוף Google Cloud . כדי לוודא ששירות ה-API Hub מופעל, אפשר לעיין בדף Hub במסוף Google Cloud .

    כניסה ל-API Hub

  9. מוודאים שמופע של Apigee מצורף לשירות של מרכז ה-API. אי אפשר להשתמש בשרת ה-proxy של MCP Discovery עם מופעי פלאגין של 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, נדרשת ההרשאה serviceusage.services.enable. אם יצרתם את הפרויקט, סביר להניח שכבר יש לכם את ההרשאה הזו דרך התפקיד 'בעלים' (roles/owner). אחרת, תוכלו לקבל את ההרשאה הזו דרך התפקיד 'אדמין בממשק Service Usage' (roles/serviceusage.serviceUsageAdmin). איך מקצים תפקידים

להפעלת ה-API

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

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

export PROJECT_ID=PROJECT_ID
export REGION=REGION
export 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 login
    gcloud config set project $PROJECT_ID

סקירה כללית

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

בקטעים הבאים מתוארים השלבים ליצירה ולפריסה של שרת 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

לפני שיוצרים ומפעילים את ה-MCP Discovery Proxy, צריך ליצור מפרט 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 שבה פרוקסי הגילוי של MCP נפרס, תוצג שגיאה כשפורסים את הפרוקסי.

יצירת שרת 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.
    • תיאור (אופציונלי): תיאור של שרת ה-proxy. לדוגמה, My first MCP Discovery Proxy.
  5. לוחצים על הבא.
  6. בקטע OpenAPI specs (מפרטי OpenAPI), משתמשים בדפדפן הקבצים כדי לבחור את קובץ OpenAPI 3.0.x שיצרתם בשלב הקודם.
  7. לוחצים על הבא.
  8. בקטע Deploy (optional), אפשר לדלג על פריסת ה-proxy בשלב הזה. לוחצים על Next.
  9. לוחצים על יצירה.

כדי לראות את נקודות הקצה של השרת והיעד של ה-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.

    בוחרים באפשרות PreFlow (לפני הזרימה) עבור נקודת קצה שמופיעה בקטע Proxy Endpoints (נקודות קצה של שרת proxy).
  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. ה-MCP proxy שפרסתם אמור להופיע ברשימה. צינור ההזנה של 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.

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