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

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

לצפייה במאמרי העזרה של Apigee Edge.

בדף הזה מוסבר איך להשתמש בשרת proxy של Apigee Discovery כדי להפוך את ממשקי ה-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 זמין לארגונים עם מינוי, עם תשלום לפי שימוש ועם הערכה, ולגרסה 1.17.0 ואילך של Apigee Hybrid. מידע נוסף זמין במאמר מבוא להקצאת הרשאות ידנית.
  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 Hub. אי אפשר להשתמש בשרת ה-proxy של MCP Discovery עם מופעי פלאגין של Apigee Edge for Public Cloud או Apigee Edge for Private Cloud ב-API Hub. מידע נוסף זמין במאמר צירוף פרויקט של סביבת זמן ריצה. אפשר לבדוק את סטטוס השיוך של פרויקט זמן הריצה בכרטיסייה Project associations בדף Settings במסוף Google Cloud .

    כניסה ל-API Hub

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

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

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

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

מפעילים את Apigee API, אם הוא עדיין לא מופעל.

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

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

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

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

יוצרים מפרט של 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:

  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 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:

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

    לדף API proxies

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

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

  1. בדף הפרטים של שרת ה-proxy, לוחצים על הכרטיסייה Develop.
  2. בקטע Proxy endpoints, לוחצים על default ואז על PreFlow.
  3. בעורך של תהליך ה-proxy, לוחצים על Add policy step.

    בוחרים באפשרות PreFlow לנקודת קצה (endpoint) שמופיעה בקטע Proxy Endpoints.
  4. בתיבת הדו-שיח Add policy step, בוחרים באפשרות Create new policy.
  5. ברשימת כללי המדיניות, בקטע Security, בוחרים באפשרות OAuth v2.0.
  6. אם רוצים, משנים את שם המדיניות ואת השם המוצג. לדוגמה, כדי לשפר את הקריאוּת, אפשר לשנות את השם המוצג ואת Name ל-VerifyAccessToken.
  7. לוחצים על הוספה.

פריסת שרת ה-proxy לגילוי MCP

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

  1. לוחצים על Deploy כדי לפתוח את החלונית Deploy proxy ל-API.
  2. השדה Revision צריך להיות מוגדר ל-1. אם לא, לוחצים על 1 כדי לבחור אותה.
  3. ברשימה Environment, בוחרים את הסביבה שבה רוצים לפרוס את שרת ה-proxy. הסביבה חייבת להיות סביבה מקיפה.
  4. מזינים את חשבון השירות שיצרתם בשלב קודם.
  5. לוחצים על 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:

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

    לממשקי ה-API של API Hub

  2. לוחצים על סינון ובוחרים באפשרות סגנון > MCP, ואז לוחצים על אישור.
  3. שרת ה-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.

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