Gestire l'accesso agli strumenti MCP con i prodotti API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questa pagina descrive come utilizzare i prodotti API Apigee per controllare l'accesso agli strumenti MCP. Indipendentemente dal fatto che utilizzi il proxy di rilevamento MCP Apigee o il traffico proxy al tuo server MCP, puoi autenticare i client MCP, applicare quote per strumento e filtrare la visibilità degli strumenti in base alla configurazione del prodotto API.

I server MCP utilizzano un singolo endpoint (ad esempio /mcp) per tutte le chiamate agli strumenti. A differenza delle API REST, in cui le operazioni si distinguono per il percorso URL e il metodo HTTP, MCP incorpora l'operazione nel corpo della richiesta JSON-RPC. Apigee utilizza la policy ParsePayload per estrarre queste operazioni in modo che le policy standard di gestione delle API, ovvero autenticazione, applicazione delle quote e filtro degli strumenti, possano essere applicate in base allo strumento.

Panoramica

Per gestire l'accesso agli strumenti MCP con i prodotti API, completa i seguenti passaggi:

  1. Aggiungi la policy ParsePayload per estrarre il nome dello strumento MCP dal corpo della richiesta.
  2. Configura un prodotto API con operazioni degli strumenti MCP e quote per strumento.
  3. Registra un'app per sviluppatori per ottenere le credenziali client.
  4. Aggiungi criteri di autenticazione (chiave API o OAuth 2.0) per verificare le credenziali client rispetto al prodotto API.
  5. Aggiungi una policy di quota per applicare limiti di frequenza per strumento.
  6. Filtro dello strumento di test per verificare che le risposte tools/list vengano filtrate in base alla configurazione del prodotto API.

Aggiungi la policy ParsePayload

Il criterio ParsePayload analizza il corpo della richiesta JSON-RPC ed estrae l'operazione MCP, ad esempio tools/call/get_weather o tools/list. L'operazione estratta viene memorizzata in una variabile di flusso con il prefisso del nome del criterio (ad esempio, parsepayload.ParsePayload-MCP.operation), che i criteri downstream utilizzano per l'autenticazione e l'applicazione delle quote.

Aggiungi la seguente norma ParsePayload al PreFlow della richiesta del proxy MCP:

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

Dove:

  • <Source>: il messaggio da analizzare. Il valore predefinito è request.
  • <PayloadType>: il formato del payload. Deve essere JSON-RPC-2.0.
  • <Protocol>: il protocollo da utilizzare per l'analisi. Deve essere MCP per i server MCP.

Dopo l'esecuzione, la policy compila le variabili di flusso con il prefisso del nome dell'istanza della policy, seguendo il pattern parsepayload.policyName.suffix. Per una policy denominata ParsePayload-MCP, vengono impostate le seguenti variabili:

Variabile di flusso Descrizione Valore di esempio
parsepayload.ParsePayload-MCP.operation Il nome dell'operazione derivato utilizzato per la corrispondenza dei prodotti API e l'applicazione della quota. tools/call/get_weather
parsepayload.ParsePayload-MCP.json-rpc.request.method Il campo method JSON-RPC della richiesta. tools/call
parsepayload.ParsePayload-MCP.json-rpc.request.id Il campo id JSON-RPC della richiesta. 1
parsepayload.ParsePayload-MCP.json-rpc.request.params.name Il campo params.name della richiesta. get_weather

Configura un prodotto API con le operazioni dello strumento MCP

Un prodotto API definisce gli strumenti MCP a cui un'applicazione client può accedere e i limiti di quota per ogni strumento. Configuri le operazioni dello strumento MCP utilizzando il campo payloadOperationGroup nella definizione del prodotto API.

Ogni voce in payloadOperationGroup.operationConfigs specifica:

  • Il proxy API che gestisce gli strumenti MCP (apiSource).
  • Una o più operazioni dello strumento (ad esempio, tools/call/get_stock_price, tools/list).
  • Una quota facoltativa per questo insieme di operazioni.
L'interfaccia utente per la creazione di prodotti API che mostra il riquadro Operazione payload con il proxy API impostato su mcp-discovery, il protocollo impostato su MCP e le opzioni del tipo di operazione MCP per Elenca e Chiama con la configurazione della quota.

Utilizza la seguente chiamata API per creare un prodotto API con operazioni dello strumento MCP:

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

Dove:

  • ORG_NAME è il nome della tua organizzazione Apigee.
  • PRODUCT_NAME è il nome interno del prodotto API.
  • PRODUCT_DISPLAY_NAME è il nome visualizzato del prodotto API.
  • MCP_PROXY_NAME è il nome del proxy API che indirizza il traffico al server MCP. Può trattarsi di un proxy di rilevamento MCP Apigee o di un proxy con il tuo server MCP come backend.

Configura le quote per strumento

Puoi configurare quote diverse per i singoli strumenti. Ad esempio, la seguente configurazione limita get_stock_price a 300 chiamate al minuto, ma limita get_company_news a sole 3 chiamate al minuto:

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

Puoi creare più prodotti API con diversi sottoinsiemi di strumenti per offrire un accesso a più livelli. Ad esempio, un prodotto Basic potrebbe includere solo tools/call/get_stock_price, mentre un prodotto Premium include tutti gli strumenti disponibili con quote più elevate. Ogni app per sviluppatori è associata a uno o più prodotti API, quindi client diversi ottengono automaticamente l'accesso a diversi set di strumenti con limiti di frequenza indipendenti.

Registrare un'app sviluppatore

Per ottenere una chiave API o credenziali OAuth per i test, registra uno sviluppatore e crea un'app per sviluppatori associata al prodotto API che hai creato nel passaggio precedente.

  1. Registra uno sviluppatore di app nella tua organizzazione Apigee.
  2. Crea un'app sviluppatore e associala al tuo prodotto API.
  3. Ottieni la chiave utente (chiave API) dalle credenziali dell'app. Utilizza questa chiave negli esempi di autenticazione che seguono.

Aggiungere criteri di autenticazione

Dopo aver aggiunto il criterio ParsePayload, aggiungi un criterio di autenticazione per verificare che il client sia autorizzato a utilizzare lo strumento MCP richiesto. Apigee confronta l'operazione estratta con le operazioni definite nel prodotto API del client.

Se lo strumento richiesto non è elencato nel prodotto API del client, Apigee restituisce un errore 401 Unauthorized.

Opzione 1: autenticazione con chiave API

Utilizza il criterio VerifyAPIKey per autenticare i client utilizzando una chiave API. Aggiungi questa policy al PreFlow della richiesta dopo la policy ParsePayload:

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

Il client passa la chiave API come parametro di query quando chiama il 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
  }'

Puoi anche configurare la policy per leggere la chiave API da un'intestazione:

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

Opzione 2: autenticazione OAuth 2.0

Utilizza il criterio OAuthV2 con l'operazione VerifyAccessToken per autenticare i client utilizzando i token di accesso OAuth 2.0. Aggiungi questa policy al PreFlow della richiesta dopo la policy ParsePayload:

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

Il client passa il token di accesso nell'intestazione 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
  }'

Per saperne di più sulla configurazione di OAuth 2.0 in Apigee, consulta la pagina Guida introduttiva a OAuth2.

Aggiungere un criterio Quota

Aggiungi una policy Quota per applicare i limiti di frequenza per strumento definiti nel prodotto API. Il criterio utilizza UseQuotaConfigInAPIProduct per applicare automaticamente la configurazione della quota dall'operazione del prodotto API corrispondente.

Aggiungi la seguente policy di quota alla richiesta PreFlow dopo la policy di autenticazione:

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

Dove AUTH_POLICY_STEP_NAME è il valore dell'attributo name nell'elemento XML della norma di autenticazione (VerifyAPIKey-1 o OAuthV2-VerifyAccessToken negli esempi di questa pagina). Deve corrispondere all'attributo name delle norme, non a <DisplayName>.

Con questa configurazione, la frequenza di ogni operazione dello strumento è limitata in modo indipendente in base alla quota definita nel prodotto API. Ad esempio, se tools/call/get_stock_price ha una quota di 300 al minuto e tools/call/get_company_news ha una quota di 3 al minuto, ogni limite viene applicato separatamente anche se si accede a entrambi gli strumenti tramite lo stesso proxy.

Completa la configurazione del proxy

L'esempio seguente mostra la configurazione completa di PreFlow della richiesta per un proxy MCP con ParsePayload, autenticazione con chiave API e applicazione della quota per strumento:

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

Filtro strumenti

Quando un client invia una richiesta tools/list tramite un proxy MCP con chiave API o autenticazione OAuth, Apigee filtra automaticamente la risposta in modo da includere solo gli strumenti registrati nel prodotto API del client.

Ad esempio, se il prodotto API di un client include le operazioni tools/call/get_stock_price e tools/call/get_company_news, una risposta tools/list dal server MCP verrà filtrata in modo da restituire solo get_stock_price e get_company_news, anche se il server MCP espone strumenti aggiuntivi.

Questo filtro viene applicato per impostazione predefinita quando è presente la seguente configurazione. Non è richiesto un criterio di filtraggio dedicato:

  • La richiesta PreFlow include ParsePayload e una norma di autenticazione (VerifyAPIKey o OAuthV2).
  • Il prodotto API include tools/list in payloadOperationGroup.
  • Il prodotto API specifica le operazioni dello strumento (ad esempio, tools/call/get_stock_price) a cui il client può accedere.

Per testare il filtro degli strumenti, invia una richiesta tools/list con la chiave API del client:

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

Se il prodotto API include tools/call/get_stock_price e tools/call/get_company_news, la risposta filtrata è simile alla seguente, anche se il server MCP espone strumenti aggiuntivi:

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

Gli strumenti non elencati nel prodotto API (ad esempio delete_account o admin_reset) vengono rimossi automaticamente dalla risposta.

La seguente sessione di debug mostra il passaggio McpToolsFilterExecution nel flusso di risposta, con la proprietà mcp_flow_info.mcp.allowed.tools che elenca gli strumenti consentiti dal prodotto API:

Sessione di debug che mostra il passaggio McpToolsFilterExecution con mcp_flow_info.mcp.allowed.tools che elenca gli strumenti filtrati.

Utilizzare i flussi condizionali per la logica per strumento

Utilizza i flussi condizionali quando hai bisogno di una logica per strumento che vada oltre le quote dei prodotti API, ad esempio l'applicazione di tassi SpikeArrest specifici per lo strumento, il routing a backend diversi o l'aggiunta di trasformazioni delle richieste per strumenti specifici. I flussi condizionali utilizzano la variabile di flusso parsepayload.policyName.operation per la corrispondenza con l'operazione MCP estratta.

Per una policy ParsePayload denominata 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>

Esegui il debug della configurazione del proxy

Utilizza lo strumento Debug di Apigee per verificare che il criterio ParsePayload estragga correttamente l'operazione MCP e che i criteri di autenticazione e quota funzionino come previsto.

Sessione di debug che mostra il passaggio ParsePayload-MCP con variabili di flusso, inclusa parsepayload.ParsePayload-MCP.operation impostata su tools/list.

Nella sessione di debug, controlla le seguenti variabili di flusso dopo il passaggio della policy ParsePayload (dove ParsePayload-MCP è il nome della policy):

  • parsepayload.ParsePayload-MCP.operation: deve contenere il nome completo dell'operazione (ad esempio, tools/call/get_stock_price).
  • parsepayload.ParsePayload-MCP.json-rpc.request.method: deve contenere il metodo JSON-RPC (ad esempio, tools/call).

Limitazioni

  • Il criterio ParsePayload supporta solo JSON-RPC-2.0 come tipo di payload.
  • Le operazioni dello strumento del prodotto API supportano solo i metodi tools/call e tools/list. Il filtro degli strumenti per le risposte tools/list si applica solo alle operazioni tools/call configurate nel prodotto API.
  • La policy ParsePayload analizza l'intero corpo della richiesta. Apigee applica un limite predefinito di 10 MB per le dimensioni del corpo della richiesta, configurabile fino a 30 MB utilizzando la proprietà request.payload.parse.limit. Per maggiori dettagli, consulta Riferimento per le proprietà degli endpoint.
  • Il criterio ParsePayload con protocollo MCP analizza solo i payload delle richieste JSON-RPC (contenenti i campi method e params). I payload di risposta MCP non vengono analizzati.
  • Il filtro degli strumenti per le risposte tools/list richiede le policy di autenticazione e ParsePayload nel PreFlow della richiesta.

Passaggi successivi