ניהול הגישה לכלי MCP באמצעות מוצרי API

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

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

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

שרתי MCP משתמשים בנקודת קצה אחת (לדוגמה, /mcp) לכל הפעלות הכלים. בניגוד לממשקי REST API שבהם הפעולות מובחנות לפי נתיב ה-URL ושיטת ה-HTTP, ב-MCP הפעולה מוטמעת בגוף הבקשה של JSON-RPC. ב-Apigee נעשה שימוש במדיניות ParsePayload כדי לחלץ את הפעולות האלה, כך שאפשר להחיל מדיניות סטנדרטית לניהול API – אימות, אכיפת מכסה וסינון כלים – על כל כלי בנפרד.

סקירה כללית

כדי לנהל את הגישה לכלי MCP באמצעות מוצרי API, צריך לבצע את השלבים הבאים:

  1. מוסיפים את המדיניות ParsePayload כדי לחלץ את שם כלי ה-MCP מגוף הבקשה.
  2. הגדרת מוצר API עם פעולות של כלי MCP ומכסות לכל כלי.
  3. רושמים אפליקציית פיתוח כדי לקבל פרטי כניסה של לקוח.
  4. מוסיפים מדיניות אימות (מפתח API או OAuth 2.0) כדי לאמת את פרטי הכניסה של הלקוח מול מוצר ה-API.
  5. מוסיפים מדיניות מכסות כדי לאכוף הגבלות קצב לכל כלי.
  6. סינון בכלי הבדיקה כדי לוודא tools/listשהתגובות מסוננות על סמך ההגדרה של מוצר ה-API.

הוספת המדיניות ParsePayload

מדיניות ParsePayload מנתחת את תוכן הבקשה בפורמט JSON-RPC ומחלצת את פעולת ה-MCP, כמו tools/call/get_weather או tools/list. הפעולה שחולצה מאוחסנת במשתנה של זרימת נתונים עם קידומת של שם המדיניות (לדוגמה, parsepayload.ParsePayload-MCP.operation), שמשמש מדיניות במורד הזרם לאימות ולאכיפת מכסות.

מוסיפים את מדיניות ParsePayload ל-PreFlow של ה-MCP proxy בבקשה:

<ParsePayload name="ParsePayload-MCP">
    <DisplayName>Parse MCP Payload</DisplayName>
    <Source>request</Source>
    <PayloadType>JSON-RPC-2.0</PayloadType>
    <Protocol>MCP</Protocol>
</ParsePayload>

כאשר:

  • <Source>: ההודעה לניתוח. ברירת המחדל היא request.
  • ‫<PayloadType>: פורמט המטען הייעודי (payload). חייב להיות JSON-RPC-2.0.
  • ‫<Protocol>: הפרוטוקול שמשמש לניתוח. חייב להיות MCP עבור שרתי MCP.

אחרי ההרצה, המדיניות מאכלסת משתני זרימה עם קידומת של שם מופע המדיניות, לפי התבנית parsepayload.policyName.suffix. עבור מדיניות בשם ParsePayload-MCP, המשתנים הבאים מוגדרים:

משתנה זרימה תיאור ערך לדוגמה
parsepayload.ParsePayload-MCP.operation שם הפעולה הנגזר שמשמש להתאמה של מוצר API ולאכיפת מכסה. tools/call/get_weather
parsepayload.ParsePayload-MCP.json-rpc.request.method השדה method של JSON-RPC מהבקשה. tools/call
parsepayload.ParsePayload-MCP.json-rpc.request.id השדה id של JSON-RPC מהבקשה. 1
parsepayload.ParsePayload-MCP.json-rpc.request.params.name השדה params.name מהבקשה. get_weather

הגדרת מוצר API באמצעות פעולות של כלי ה-MCP

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

כל רשומה ב-payloadOperationGroup.operationConfigs מציינת:

  • ה-proxy ל-API שמשרת את כלי ה-MCP‏ (apiSource).
  • פעולה אחת או יותר של כלי (לדוגמה, tools/call/get_stock_price, tools/list).
  • מכסה אופציונלית לקבוצת הפעולות הזו.
ממשק המשתמש ליצירת מוצר API שבו מוצג החלונית Payload Operation עם API Proxy שהוגדר ל-mcp-discovery,‏ Protocol שהוגדר ל-MCP ואפשרויות MCP Operation Type ל-List ול-Call עם הגדרת מכסת נתונים.

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

curl -X POST \
  "https://apigee.googleapis.com/v1/organizations/ORG_NAME/apiproducts" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "PRODUCT_NAME",
    "displayName": "PRODUCT_DISPLAY_NAME",
    "approvalType": "auto",
    "payloadOperationGroup": {
      "operationConfigs": [
        {
          "apiSource": "MCP_PROXY_NAME",
          "operations": [
            { "operation": "tools/call/get_stock_price" },
            { "operation": "tools/call/get_company_news" }
          ],
          "quota": {
            "limit": "100",
            "interval": "1",
            "timeUnit": "minute"
          }
        },
        {
          "apiSource": "MCP_PROXY_NAME",
          "operations": [
            { "operation": "tools/list" }
          ],
          "quota": {
            "limit": "300",
            "interval": "1",
            "timeUnit": "minute"
          }
        }
      ]
    }
  }'

כאשר:

  • ‫ORG_NAME הוא השם של הארגון שלכם ב-Apigee.
  • ‫PRODUCT_NAME הוא השם הפנימי של מוצר ה-API.
  • ‫PRODUCT_DISPLAY_NAME הוא השם המוצג של מוצר ה-API.
  • ‫MCP_PROXY_NAME הוא השם של proxy ל-API שמנתב את התנועה לשרת ה-MCP. יכול להיות שזה שרת proxy של Apigee MCP Discovery או שרת proxy עם שרת ה-MCP שלכם כקצה העורפי.

הגדרת מכסות לכל כלי

אפשר להגדיר מכסות שונות לכל כלי בנפרד. לדוגמה, ההגדרה הבאה מגבילה את get_stock_price ל-300 שיחות בדקה, אבל מגבילה את get_company_news ל-3 שיחות בדקה בלבד:

{
  "payloadOperationGroup": {
    "operationConfigs": [
      {
        "apiSource": "MCP_PROXY_NAME",
        "operations": [
          { "operation": "tools/call/get_stock_price" }
        ],
        "quota": { "limit": "300", "interval": "1", "timeUnit": "minute" }
      },
      {
        "apiSource": "MCP_PROXY_NAME",
        "operations": [
          { "operation": "tools/call/get_company_news" }
        ],
        "quota": { "limit": "3", "interval": "1", "timeUnit": "minute" }
      },
      {
        "apiSource": "MCP_PROXY_NAME",
        "operations": [
          { "operation": "tools/list" }
        ],
        "quota": { "limit": "300", "interval": "1", "timeUnit": "minute" }
      }
    ]
  }
}

אתם יכולים ליצור כמה מוצרי API עם קבוצות משנה שונות של כלים כדי להציע מודל עם כמה רמות גישה. לדוגמה, מוצר Basic יכול לכלול רק את tools/call/get_stock_price, בעוד שמוצר Premium כולל את כל הכלים הזמינים עם מכסות גבוהות יותר. כל אפליקציה למפתחים משויכת למוצר API אחד או יותר, כך שלקוחות שונים מקבלים גישה אוטומטית לקבוצות שונות של כלים עם מכסות נפרדות.

רישום אפליקציית מפתח

כדי לקבל מפתח API או פרטי כניסה ל-OAuth לצורך בדיקה, צריך לרשום מפתח וליצור אפליקציה למפתחים שמשויכת למוצר ה-API שיצרתם בשלב הקודם.

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

הוספת מדיניות אימות

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

אם הכלי המבוקש לא מופיע במוצר ה-API של הלקוח, Apigee מחזיר שגיאה 401 Unauthorized.

אפשרות 1: אימות באמצעות מפתח API

משתמשים במדיניות VerifyAPIKey כדי לאמת לקוחות באמצעות מפתח API. מוסיפים את המדיניות הזו ל-PreFlow של הבקשה אחרי מדיניות ParsePayload:

<VerifyAPIKey name="VerifyAPIKey-1">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.queryparam.apikey"/>
</VerifyAPIKey>

הלקוח מעביר את מפתח ה-API כפרמטר של שאילתה כשקוראים ל-Proxy של MCP:

curl -X POST "https://RUNTIME_HOSTNAME/mcp?apikey=API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": { "name": "get_stock_price", "arguments": { "ticker": "GOOGL" } },
    "id": 1
  }'

אפשר גם להגדיר את המדיניות כך שתקרא את מפתח ה-API מכותרת:

<VerifyAPIKey name="VerifyAPIKey-1">
    <DisplayName>Verify API Key</DisplayName>
    <APIKey ref="request.header.x-api-key"/>
</VerifyAPIKey>

אפשרות 2: אימות OAuth 2.0

משתמשים במדיניות OAuthV2 עם הפעולה VerifyAccessToken כדי לאמת לקוחות באמצעות אסימוני גישה מסוג OAuth 2.0. מוסיפים את המדיניות הזו ל-PreFlow של הבקשה אחרי מדיניות ParsePayload:

<OAuthV2 name="OAuthV2-VerifyAccessToken">
    <DisplayName>Verify OAuth Access Token</DisplayName>
    <Operation>VerifyAccessToken</Operation>
</OAuthV2>

הלקוח מעביר את אסימון הגישה בכותרת Authorization:

curl -X POST "https://RUNTIME_HOSTNAME/mcp" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": { "name": "get_stock_price", "arguments": { "ticker": "GOOGL" } },
    "id": 1
  }'

מידע נוסף על הגדרת OAuth 2.0 ב-Apigee זמין במאמר תחילת העבודה עם OAuth2.

הוספה של מדיניות מכסת נפח

מוסיפים מדיניות Quota כדי לאכוף את מגבלות הקצב לכל כלי שמוגדרות במוצר ה-API. המדיניות משתמשת ב-UseQuotaConfigInAPIProduct כדי להחיל באופן אוטומטי את הגדרת המכסה מפעולת מוצר ה-API התואמת.

מוסיפים את מדיניות המכסה הבאה ל-PreFlow של הבקשה אחרי מדיניות האימות:

<Quota name="Quota-PerToolLimit">
    <DisplayName>Per-Tool Quota</DisplayName>
    <UseQuotaConfigInAPIProduct stepName="AUTH_POLICY_STEP_NAME"/>
    <Distributed>true</Distributed>
</Quota>

‫AUTH_POLICY_STEP_NAME הוא הערך של המאפיין name ברכיב ה-XML של מדיניות האימות (VerifyAPIKey-1 או OAuthV2-VerifyAccessToken בדוגמאות שבדף הזה). הערך הזה צריך להיות זהה לערך של מאפיין המדיניות name, ולא לערך של מאפיין <DisplayName>.

במקרה כזה, כל פעולה בכלי מוגבלת בנפרד לפי המכסה שמוגדרת במוצר ה-API. לדוגמה, אם למכסת tools/call/get_stock_price יש 300 בקשות לדקה ולמכסת tools/call/get_company_news יש 3 בקשות לדקה, כל מגבלה נאכפת בנפרד, גם אם הגישה לשני הכלים מתבצעת דרך אותו שרת proxy.

השלמת ההגדרה של שרת proxy

בדוגמה הבאה מוצגת ההגדרה המלאה של PreFlow לבקשה של פרוקסי MCP עם ParsePayload, אימות מפתח API ואכיפת מכסה לכל כלי:

<ProxyEndpoint name="default">
    <PreFlow>
        <Request>
            <Step>
                <Name>ParsePayload-MCP</Name>
            </Step>
            <Step>
                <Name>VerifyAPIKey-1</Name>
            </Step>
            <Step>
                <Name>Quota-PerToolLimit</Name>
            </Step>
        </Request>
    </PreFlow>
    <HTTPProxyConnection>
        <BasePath>/mcp</BasePath>
    </HTTPProxyConnection>
    <RouteRule name="default">
        <TargetEndpoint>default</TargetEndpoint>
    </RouteRule>
</ProxyEndpoint>

סינון כלי עבודה

כשלקוח שולח בקשת tools/list דרך שרת proxy של MCP עם מפתח API או אימות OAuth, מערכת Apigee מסננת באופן אוטומטי את התגובה כך שיכללו בה רק הכלים שרשומים במוצר ה-API של הלקוח.

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

הסינון הזה מתבצע כברירת מחדל כשההגדרה הבאה מוגדרת. לא נדרשת מדיניות סינון ייעודית:

  • הבקשה PreFlow כוללת את ParsePayload ומדיניות אימות (VerifyAPIKey או OAuthV2).
  • מוצר ה-API כולל את tools/list ב-payloadOperationGroup.
  • במוצר ה-API מוגדרות הפעולות בכלי (לדוגמה, tools/call/get_stock_price) שהלקוח יכול לגשת אליהן.

כדי לבדוק את הסינון של הכלי, שולחים בקשת tools/list עם מפתח ה-API של הלקוח:

curl -X POST "https://RUNTIME_HOSTNAME/mcp?apikey=API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

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

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "get_stock_price",
        "description": "Get the current stock price for a given ticker symbol.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "ticker": { "type": "string", "description": "Stock ticker symbol" }
          },
          "required": ["ticker"]
        }
      },
      {
        "name": "get_company_news",
        "description": "Get recent news articles for a company.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "company": { "type": "string", "description": "Company name" }
          },
          "required": ["company"]
        }
      }
    ]
  },
  "id": 1
}

כלים שלא מופיעים במוצר ה-API (לדוגמה, delete_account או admin_reset) מוסרים אוטומטית מהתגובה.

בסשן הניפוי הבא מוצג השלב McpToolsFilterExecution בתהליך התגובה, עם המאפיין mcp_flow_info.mcp.allowed.tools שמפרט את הכלים שמותרים על ידי מוצר ה-API:

סשן ניפוי באגים שבו מוצג השלב McpToolsFilterExecution עם mcp_flow_info.mcp.allowed.tools שבו מפורטים הכלים שסוננו.

שימוש בתהליכים מותנים ללוגיקה של כל כלי

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

עבור מדיניות ParsePayload בשם ParsePayload-MCP:

<Flows>
    <Flow name="ListTools">
        <Condition>(parsepayload.ParsePayload-MCP.operation = "tools/list")</Condition>
        <Request/>
    </Flow>
    <Flow name="GetStockPrice">
        <Condition>(parsepayload.ParsePayload-MCP.operation = "tools/call/get_stock_price")</Condition>
        <Request>
            <Step>
                <Name>SpikeArrest-StockPrice</Name>
            </Step>
        </Request>
    </Flow>
    <Flow name="GetCompanyNews">
        <Condition>(parsepayload.ParsePayload-MCP.operation = "tools/call/get_company_news")</Condition>
        <Request>
            <Step>
                <Name>SpikeArrest-CompanyNews</Name>
            </Step>
        </Request>
    </Flow>
</Flows>

ניפוי באגים בהגדרת ה-proxy

כדי לוודא שמדיניות ParsePayload מחלצת את פעולת ה-MCP בצורה נכונה, ושמדיניות האימות והמכסה פועלות כמצופה, אפשר להשתמש בכלי Debug של Apigee.

סשן ניפוי באגים שבו מוצג השלב ParsePayload-MCP עם משתני זרימה, כולל parsepayload.ParsePayload-MCP.operation שהוגדר ל-tools/list.

בסשן הניפוי באגים, בודקים את משתני התהליך הבאים אחרי השלב ParsePayload (כאשר ParsePayload-MCP הוא שם המדיניות):

  • ‫parsepayload.ParsePayload-MCP.operation: צריך להכיל את שם הפעולה המלא (לדוגמה, tools/call/get_stock_price).
  • ‫parsepayload.ParsePayload-MCP.json-rpc.request.method: צריך להכיל את ה-method של JSON-RPC (לדוגמה, tools/call).

מגבלות

  • המדיניות ParsePayload תומכת רק ב-JSON-RPC-2.0 כסוג מטען ייעודי (payload).
  • פעולות של כלי מוצר API תומכות רק ב-methods‏ tools/call ו-tools/list. סינון כלי tools/list התגובות חל רק על פעולות tools/call שהוגדרו במוצר ה-API.
  • המדיניות ParsePayload מנתחת את כל גוף הבקשה. ב-Apigee מוגדרת כברירת מחדל מגבלה על גודל גוף הבקשה של 10MB, שאפשר להגדיר עד 30MB באמצעות המאפיין request.payload.parse.limit. פרטים נוספים זמינים במאמר בנושא מאפייני נקודות קצה.
  • המדיניות ParsePayload עם פרוטוקול MCP מנתחת רק מטען ייעודי (payload) של בקשות JSON-RPC (שמכיל את השדות method ו-params). מטענים ייעודיים (payloads) של תגובות MCP לא מנותחים.
  • כדי לסנן את התגובות של tools/list באמצעות כלי, צריך להשתמש במדיניות ParsePayload ובמדיניות אימות ב-PreFlow של הבקשה.

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