Zugriff auf MCP-Tools mit API-Produkten verwalten

Diese Seite gilt für Apigee und Apigee Hybrid.

Apigee Edge-Dokumentation aufrufen

Auf dieser Seite wird beschrieben, wie Sie mit Apigee-API-Produkten den Zugriff auf MCP-Tools steuern. Unabhängig davon, ob Sie den Apigee MCP Discovery-Proxy oder den Proxy-Traffic zu Ihrem eigenen MCP-Server verwenden, können Sie MCP-Clients authentifizieren, Tool-spezifische Kontingente anwenden und die Sichtbarkeit von Tools basierend auf der API-Produktkonfiguration filtern.

Hinweis (Apigee Hybrid): Alle API-Produkt-, ParsePayload-, OAuthV2-, VerifyAPIKey- und Kontingentrichtlinienkonfigurationen auf dieser Seite gelten identisch für Apigee Hybrid. Richtlinien werden auf der Apigee-Steuerungsebene erstellt und vom Apigee-Nachrichtenprozessor in Ihrem Cluster erzwungen.

MCP-Server verwenden für alle Toolaufrufe einen einzelnen Endpunkt (z. B. /mcp). Im Gegensatz zu REST APIs, bei denen Vorgänge durch URL-Pfad und HTTP-Methode unterschieden werden, wird der Vorgang bei MCP in den JSON-RPC-Anfragetext eingebettet. Apigee verwendet die ParsePayload-Richtlinie, um diese Vorgänge zu extrahieren, damit Standardrichtlinien für die API-Verwaltung (Authentifizierung, Kontingenterzwingung und Tool-Filterung) auf Tool-Basis angewendet werden können.

Hinweis:In dieser Anleitung wird davon ausgegangen, dass Sie einen API-Proxy bereitgestellt haben, der Traffic an Ihren MCP-Server weiterleitet. Sie können den Apigee MCP Discovery-Proxy verwenden oder einen API-Proxy erstellen, bei dem Ihr eigener MCP-Server das Backend-Ziel ist.

Übersicht

So verwalten Sie den Zugriff auf das MCP-Tool mit API-Produkten:

1. Fügen Sie die ParsePayload-Richtlinie hinzu, um den Namen des MCP-Tools aus dem Anfragetext zu extrahieren.
2. Konfigurieren Sie ein API-Produkt mit MCP-Toolvorgängen und Tool-spezifischen Kontingenten.
3. Registrieren Sie eine Entwickler-App, um Client-Anmeldedaten zu erhalten.
4. Fügen Sie Authentifizierungsrichtlinien (API-Schlüssel oder OAuth 2.0) hinzu, um Clientanmeldedaten für das API-Produkt zu prüfen.
5. Fügen Sie eine Kontingentrichtlinie hinzu, um Ratenbegrenzungen pro Tool zu erzwingen.
6. Testtool-Filterung, um zu bestätigen, dass tools/list-Antworten basierend auf der API-Produktkonfiguration gefiltert werden.

ParsePayload-Richtlinie hinzufügen

Mit der Richtlinie ParsePayload wird der JSON-RPC-Anfragetext geparst und der MCP-Vorgang extrahiert, z. B. tools/call/get_weather oder tools/list. Der extrahierte Vorgang wird in einer Ablaufvariablen gespeichert, die mit dem Richtliniennamen beginnt (z. B. parsepayload.ParsePayload-MCP.operation). Nachgelagerte Richtlinien verwenden diese Variable für die Authentifizierung und die Kontingenterzwingung.

Fügen Sie dem Anfrage-PreFlow Ihres MCP-Proxys die folgende ParsePayload-Richtlinie hinzu:

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

Wobei:

• <Source>: Die zu parsende Nachricht. Die Standardeinstellung ist request.
• <PayloadType>: Das Nutzlastformat. Muss JSON-RPC-2.0 lauten.
• <Protocol>: Das zum Parsen zu verwendende Protokoll. Muss MCP für MCP-Server sein.

Nach der Ausführung werden Ablaufvariablen mit dem Präfix des Richtlinieninstanznamens gemäß dem Muster parsepayload.policyName.suffix eingefügt. Für eine Richtlinie mit dem Namen ParsePayload-MCP werden die folgenden Variablen festgelegt:

Ablaufvariable	Beschreibung	Beispielwert
parsepayload.ParsePayload-MCP.operation	Der abgeleitete Vorgangsname, der für den Abgleich von API-Produkten und die Durchsetzung von Kontingenten verwendet wird.	tools/call/get_weather
parsepayload.ParsePayload-MCP.json-rpc.request.method	Das Feld method in der JSON-RPC-Anfrage.	tools/call
parsepayload.ParsePayload-MCP.json-rpc.request.id	Das Feld id in der JSON-RPC-Anfrage.	1
parsepayload.ParsePayload-MCP.json-rpc.request.params.name	Das Feld params.name aus der Anfrage.	get_weather

Hinweis:Die ParsePayload-Richtlinie muss vor allen Authentifizierungs- oder Kontingentrichtlinien im PreFlow der Anfrage platziert werden, da diese Richtlinien von der extrahierten Vorgangsflussvariablen für den API-Produktabgleich abhängen.

API-Produkt mit MCP-Tool-Vorgängen konfigurieren

In einem API-Produkt wird definiert, auf welche MCP-Tools eine Clientanwendung zugreifen kann und welche Kontingentlimits für jedes Tool gelten. Sie konfigurieren MCP-Toolvorgänge mit dem Feld payloadOperationGroup in der API-Produktdefinition.

Jeder Eintrag in payloadOperationGroup.operationConfigs gibt Folgendes an:

• Der API-Proxy, der die MCP-Tools bereitstellt (apiSource).
• Ein oder mehrere Tool-Vorgänge (z. B. tools/call/get_stock_price, tools/list).
• Ein optionales Kontingent für diese Vorgänge.

Verwenden Sie den folgenden API-Aufruf, um ein API-Produkt mit MCP-Toolvorgängen zu erstellen:

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"
          }
        }
      ]
    }
  }'

Wobei:

• ORG_NAME ist der Name Ihrer Apigee-Organisation.
• PRODUCT_NAME ist der interne Name des API-Produkts.
• PRODUCT_DISPLAY_NAME ist der Anzeigename des API-Produkts.
• MCP_PROXY_NAME ist der Name des API-Proxy, der Traffic an Ihren MCP-Server weiterleitet. Das kann ein Apigee-MCP-Discovery-Proxy oder ein Proxy mit Ihrem eigenen MCP-Server als Backend sein.

Kontingente für einzelne Tools konfigurieren

Sie können für einzelne Tools unterschiedliche Kontingente konfigurieren. Die folgende Konfiguration beschränkt beispielsweise get_stock_price auf 300 Aufrufe pro Minute, get_company_news jedoch auf nur 3 Aufrufe pro Minute:

{
  "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" }
      }
    ]
  }
}

Hinweis:Fügen Sie tools/list als Vorgang in Ihr API-Produkt ein, wenn der Client verfügbare Tools ermitteln können soll. Wenn tools/list nicht enthalten ist, kann der Kunde keine Tools über dieses API-Produkt auflisten.

Sie können mehrere API-Produkte mit unterschiedlichen Tool-Teilmengen erstellen, um gestaffelten Zugriff anzubieten. Ein Basic-Produkt enthält beispielsweise nur tools/call/get_stock_price, während ein Premium-Produkt alle verfügbaren Tools mit höheren Kontingenten umfasst. Jede Entwickler-App ist einem oder mehreren API-Produkten zugeordnet. Dadurch erhalten verschiedene Clients automatisch Zugriff auf unterschiedliche Toolsets mit unabhängigen Ratenbeschränkungen.

Entwickler-App registrieren

Um einen API-Schlüssel oder OAuth-Anmeldedaten für Tests zu erhalten, registrieren Sie einen Entwickler und erstellen Sie eine Entwickler-App, die mit dem API-Produkt verknüpft ist, das Sie im vorherigen Schritt erstellt haben.

1. App-Entwickler in Ihrer Apigee-Organisation registrieren
2. Entwickler-App erstellen und mit Ihrem API-Produkt verknüpfen
3. Rufen Sie den Consumer-Key (API-Schlüssel) aus den Anmeldedaten der App ab. Verwenden Sie diesen Schlüssel in den folgenden Authentifizierungsbeispielen.

Authentifizierungsrichtlinien hinzufügen

Nachdem Sie die ParsePayload-Richtlinie hinzugefügt haben, fügen Sie eine Authentifizierungsrichtlinie hinzu, um zu prüfen, ob der Client berechtigt ist, das angeforderte MCP-Tool zu verwenden. Apigee gleicht den extrahierten Vorgang mit den Vorgängen ab, die im API-Produkt des Clients definiert sind.

Wenn das angeforderte Tool nicht im API-Produkt des Clients aufgeführt ist, gibt Apigee einen 401 Unauthorized-Fehler zurück.

Hinweis:Platzieren Sie die Authentifizierungsrichtlinie nach der ParsePayload-Richtlinie und vor der Kontingentrichtlinie im Anfrage-PreFlow. Die vollständige Richtlinienreihenfolge finden Sie unter Proxykonfiguration abschließen.

Option 1: Authentifizierung von API-Schlüsseln

Verwenden Sie die VerifyAPIKey-Richtlinie, um Clients mit einem API-Schlüssel zu authentifizieren. Fügen Sie diese Richtlinie dem Anfrage-PreFlow nach der ParsePayload-Richtlinie hinzu:

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

Der Client übergibt den API-Schlüssel als Abfrageparameter beim Aufrufen des MCP-Proxys:

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
  }'

Sie können die Richtlinie auch so konfigurieren, dass der API-Schlüssel aus einem Header gelesen wird:

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

Option 2: Authentifizierung mit OAuth 2.0

Verwenden Sie die OAuthV2-Richtlinie mit dem Vorgang VerifyAccessToken, um Clients mit OAuth 2.0-Zugriffstokens zu authentifizieren. Fügen Sie diese Richtlinie dem Anfrage-PreFlow nach der ParsePayload-Richtlinie hinzu:

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

Der Client übergibt das Zugriffstoken im Authorization-Header:

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
  }'

Weitere Informationen zum Konfigurieren von OAuth 2.0 in Apigee finden Sie unter Erste Schritte mit OAuth2.

Kontingentrichtlinie hinzufügen

Fügen Sie eine Quota-Richtlinie hinzu, um die im API-Produkt definierten Ratenbeschränkungen pro Tool zu erzwingen. In der Richtlinie wird UseQuotaConfigInAPIProduct verwendet, um die Kontingentkonfiguration aus dem übereinstimmenden API-Produktvorgang automatisch anzuwenden.

Hinweis:Die Kontingentrichtlinie muss nach der ParsePayload- und der Authentifizierungsrichtlinie im PreFlow der Anfrage stehen. Die vollständige Richtlinienreihenfolge finden Sie unter Proxykonfiguration abschließen.

Fügen Sie die folgende Kontingentrichtlinie nach der Authentifizierungsrichtlinie zum Anfrage-PreFlow hinzu:

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

Dabei ist AUTH_POLICY_STEP_NAME der Wert des Attributs name im XML-Element der Authentifizierungsrichtlinie (entweder VerifyAPIKey-1 oder OAuthV2-VerifyAccessToken in den Beispielen auf dieser Seite). Dies muss mit dem Richtlinienattribut name übereinstimmen, nicht mit <DisplayName>.

Bei dieser Konfiguration wird jeder Toolvorgang unabhängig voneinander gemäß dem im API-Produkt definierten Kontingent begrenzt. Wenn tools/call/get_stock_price beispielsweise ein Kontingent von 300 Anfragen pro Minute und tools/call/get_company_news ein Kontingent von 3 Anfragen pro Minute hat, wird jedes Limit separat durchgesetzt, auch wenn auf beide Tools über denselben Proxy zugegriffen wird.

Proxykonfiguration abschließen

Das folgende Beispiel zeigt die vollständige PreFlow-Konfiguration für Anfragen für einen MCP-Proxy mit ParsePayload, API-Schlüsselauthentifizierung und Kontingentdurchsetzung pro Tool:

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

Wenn ein Client eine tools/list-Anfrage über einen MCP-Proxy mit API-Schlüssel oder OAuth-Authentifizierung sendet, filtert Apigee die Antwort automatisch so, dass nur die Tools enthalten sind, die im API-Produkt des Clients registriert sind.

Wenn das API-Produkt eines Clients beispielsweise die Vorgänge tools/call/get_stock_price und tools/call/get_company_news enthält, wird eine tools/list-Antwort des MCP-Servers gefiltert, sodass nur get_stock_price und get_company_news zurückgegeben werden, auch wenn der MCP-Server zusätzliche Tools bereitstellt.

Diese Filterung erfolgt standardmäßig, wenn die folgende Konfiguration vorhanden ist. Es ist keine spezielle Filterrichtlinie erforderlich:

• Der PreFlow für Anfragen enthält die ParsePayload-Richtlinie und eine Authentifizierungsrichtlinie (VerifyAPIKey oder OAuthV2).
• Das API-Produkt enthält tools/list im payloadOperationGroup.
• Im API-Produkt werden die Tool-Vorgänge (z. B. tools/call/get_stock_price) angegeben, auf die der Client zugreifen darf.

Wenn Sie die Tool-Filterung testen möchten, senden Sie eine tools/list-Anfrage mit dem API-Schlüssel des Kunden:

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

Wenn das API-Produkt tools/call/get_stock_price und tools/call/get_company_news enthält, sieht die gefilterte Antwort so aus, auch wenn der MCP-Server zusätzliche Tools bereitstellt:

{
  "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
}

Tools, die nicht im API-Produkt aufgeführt sind (z. B. delete_account oder admin_reset), werden automatisch aus der Antwort entfernt.

In der folgenden Fehlerbehebungssitzung wird der Schritt McpToolsFilterExecution im Antwortablauf gezeigt. In der Eigenschaft mcp_flow_info.mcp.allowed.tools werden die vom API-Produkt zugelassenen Tools aufgeführt:

Bedingte Abläufe für die Logik pro Tool verwenden

Verwenden Sie bedingte Abläufe, wenn Sie eine Tool-spezifische Logik benötigen, die über die API-Produktkontingente hinausgeht, z. B. das Anwenden von Tool-spezifischen SpikeArrest-Raten, das Weiterleiten an verschiedene Back-Ends oder das Hinzufügen von Anfragetransformationen für bestimmte Tools. Bei bedingten Abläufen wird die Ablaufvariable parsepayload.policyName.operation verwendet, um den extrahierten MCP-Vorgang abzugleichen.

Für eine ParsePayload-Richtlinie mit dem Namen 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>

Proxykonfiguration debuggen

Verwenden Sie das Apigee-Tool Debug, um zu prüfen, ob die ParsePayload-Richtlinie den MCP-Vorgang korrekt extrahiert und ob die Authentifizierungs- und Kontingentrichtlinien wie erwartet funktionieren.

Prüfen Sie in der Debugging-Sitzung nach dem Schritt „ParsePayload“-Richtlinie (wobei ParsePayload-MCP der Richtlinienname ist) die folgenden Ablaufvariablen:

• parsepayload.ParsePayload-MCP.operation: Sollte den vollständigen Vorgangsnamen enthalten, z. B. tools/call/get_stock_price.
• parsepayload.ParsePayload-MCP.json-rpc.request.method: Sollte die JSON-RPC-Methode enthalten (z. B. tools/call).

Beschränkungen

• Die ParsePayload-Richtlinie unterstützt nur JSON-RPC-2.0 als Nutzlasttyp.
• API-Produkt-Tool-Vorgänge unterstützen nur die Methoden tools/call und tools/list. Die Tool-Filterung für tools/list-Antworten gilt nur für tools/call-Vorgänge, die im API-Produkt konfiguriert sind.
• Die ParsePayload-Richtlinie parst den gesamten Anfragetext. Apigee erzwingt ein Standardgrößenlimit für den Anfragetext von 10 MB, das mit der Eigenschaft request.payload.parse.limit auf bis zu 30 MB konfiguriert werden kann. Weitere Informationen finden Sie in der Referenz für Endpunktattribute.
• Die ParsePayload-Richtlinie mit dem MCP-Protokoll parst nur JSON-RPC-Anfragenutzlasten (mit den Feldern method und params). MCP-Antwortnutzlasten werden nicht geparst.
• Für die Toolfilterung für tools/list-Antworten sind die Richtlinien „ParsePayload“ und „Authentifizierung“ im PreFlow der Anfrage erforderlich.

Nächste Schritte

• Weitere Informationen zu MCP in Apigee finden Sie unter MCP in Apigee – Übersicht.
• Erste Schritte mit Apigee und MCP
• Informationen zu API-Produkten und Verwalten von API-Produkten
• Weitere Informationen zur Ratenbegrenzung in Apigee
• API-Schlüssel und OAuth 2.0-Authentifizierung