Administra el acceso a las herramientas de MCP con productos de API

Esta página se aplica a Apigee y Apigee Hybrid.

Consulta la documentación de Apigee Edge.

En esta página, se describe cómo usar los productos de API de Apigee para controlar el acceso a las herramientas de MCP. Ya sea que uses el proxy de detección de MCP de Apigee o el tráfico de proxy a tu propio servidor de MCP, puedes autenticar clientes de MCP, aplicar cuotas por herramienta y filtrar la visibilidad de las herramientas según la configuración del producto de API.

Los servidores de MCP usan un solo extremo (por ejemplo, /mcp) para todas las invocaciones de herramientas. A diferencia de las APIs de REST, en las que las operaciones se distinguen por la ruta de URL y el método HTTP, la MCP incorpora la operación en el cuerpo de la solicitud de JSON-RPC. Apigee usa la política ParsePayload para extraer estas operaciones, de modo que las políticas estándar de administración de APIs (autenticación, aplicación de cuotas y filtrado de herramientas) se puedan aplicar por herramienta.

Descripción general

Para administrar el acceso a la herramienta de MCP con productos de API, completa los siguientes pasos:

  1. Agrega la política ParsePayload para extraer el nombre de la herramienta de MCP del cuerpo de la solicitud.
  2. Configura un producto de API con operaciones de herramientas de MCP y cuotas por herramienta.
  3. Registra una app de desarrollador para obtener credenciales de cliente.
  4. Agrega políticas de autenticación (clave de API o OAuth 2.0) para verificar las credenciales del cliente en el producto de API.
  5. Agrega una política de cuota para aplicar límites de frecuencia por herramienta.
  6. Filtrado de la herramienta de prueba para confirmar que las respuestas de tools/list se filtran según la configuración del producto de API

Agrega la política ParsePayload

La política ParsePayload analiza el cuerpo de la solicitud de JSON-RPC y extrae la operación de MCP, como tools/call/get_weather o tools/list. La operación extraída se almacena en una variable de flujo con el prefijo del nombre de la política (por ejemplo, parsepayload.ParsePayload-MCP.operation), que las políticas posteriores usan para la autenticación y la aplicación de la cuota.

Agrega la siguiente política ParsePayload al flujo previo de solicitud de tu proxy de MCP:

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

Aquí:

  • <Source>: Es el mensaje que se analizará. La configuración predeterminada es request.
  • <PayloadType>: Es el formato de la carga útil. Debe ser JSON-RPC-2.0.
  • <Protocol>: Es el protocolo que se usará para el análisis. Debe ser MCP para los servidores de MCP.

Después de la ejecución, la política propaga variables de flujo con el prefijo del nombre de la instancia de la política, según el patrón parsepayload.policyName.suffix. Para una política llamada ParsePayload-MCP, se configuran las siguientes variables:

Variable de flujo Descripción Valor de ejemplo
parsepayload.ParsePayload-MCP.operation Es el nombre de la operación derivada que se usa para la aplicación de cuotas y la coincidencia de productos de API. tools/call/get_weather
parsepayload.ParsePayload-MCP.json-rpc.request.method Es el campo method de JSON-RPC de la solicitud. tools/call
parsepayload.ParsePayload-MCP.json-rpc.request.id Es el campo id de JSON-RPC de la solicitud. 1
parsepayload.ParsePayload-MCP.json-rpc.request.params.name Es el campo params.name de la solicitud. get_weather

Configura un producto de API con operaciones de herramientas de MCP

Un producto de API define a qué herramientas de MCP puede acceder una aplicación cliente y los límites de cuota para cada herramienta. Configura las operaciones de la herramienta de MCP con el campo payloadOperationGroup en la definición del producto de API.

Cada entrada en payloadOperationGroup.operationConfigs especifica lo siguiente:

  • Es el proxy de API que entrega las herramientas del MCP (apiSource).
  • Una o más operaciones de herramientas (por ejemplo, tools/call/get_stock_price, tools/list).
  • Es una cuota opcional para ese conjunto de operaciones.
La IU de creación de productos de API muestra el panel Operación de carga útil con el proxy de API establecido en mcp-discovery, el protocolo establecido en MCP y las opciones de tipo de operación de MCP para List y Call con la configuración de cuota.

Usa la siguiente llamada a la API para crear un producto de API con operaciones de la herramienta de 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"
          }
        }
      ]
    }
  }'

Aquí:

  • ORG_NAME es el nombre de tu organización de Apigee.
  • PRODUCT_NAME es el nombre interno del producto de API.
  • PRODUCT_DISPLAY_NAME es el nombre visible del producto de API.
  • MCP_PROXY_NAME es el nombre del proxy de API que enruta el tráfico a tu servidor de MCP. Puede ser un proxy de detección de MCP de Apigee o un proxy con tu propio servidor de MCP como backend.

Configura cuotas por herramienta

Puedes configurar diferentes cuotas para herramientas individuales. Por ejemplo, la siguiente configuración limita get_stock_price a 300 llamadas por minuto, pero restringe get_company_news a solo 3 llamadas por 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" }
      }
    ]
  }
}

Puedes crear varios productos de API con diferentes subconjuntos de herramientas para ofrecer acceso por niveles. Por ejemplo, un producto Básico podría incluir solo tools/call/get_stock_price, mientras que un producto Premium incluye todas las herramientas disponibles con cuotas más altas. Cada app para desarrolladores está asociada con uno o más productos de API, por lo que los diferentes clientes obtienen automáticamente acceso a diferentes conjuntos de herramientas con límites de frecuencia independientes.

Registre una aplicación de desarrollador

Para obtener una clave de API o credenciales de OAuth para realizar pruebas, registra un desarrollador y crea una app para desarrolladores asociada al producto de API que creaste en el paso anterior.

  1. Registra un desarrollador de apps en tu organización de Apigee.
  2. Crea una app para desarrolladores y asóciala con tu producto de API.
  3. Obtén la clave de consumidor (clave de API) de las credenciales de la app. Usa esta clave en los ejemplos de autenticación que se muestran a continuación.

Agrega políticas de autenticación

Después de agregar la política ParsePayload, agrega una política de autenticación para verificar que el cliente esté autorizado a usar la herramienta de MCP solicitada. Apigee compara la operación extraída con las operaciones definidas en el producto de API del cliente.

Si la herramienta solicitada no aparece en el producto de API del cliente, Apigee devuelve un error 401 Unauthorized.

Opción 1: Autenticación de la clave de API

Usa la política VerifyAPIKey para autenticar clientes con una clave de API. Agrega esta política al PreFlow de solicitud después de la política ParsePayload:

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

El cliente pasa la clave de API como un parámetro de consulta cuando llama al proxy de 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
  }'

También puedes configurar la política para que lea la clave de API desde un encabezado:

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

Opción 2: Autenticación OAuth 2.0

Usa la política OAuthV2 con la operación VerifyAccessToken para autenticar clientes con tokens de acceso de OAuth 2.0. Agrega esta política al PreFlow de solicitud después de la política ParsePayload:

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

El cliente pasa el token de acceso en el encabezado 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
  }'

Si deseas obtener más información para configurar OAuth 2.0 en Apigee, consulta Cómo comenzar a usar OAuth2.

Agrega una política de cuotas

Agrega una política de Quota para aplicar los límites de frecuencia por herramienta definidos en el producto de API. La política usa UseQuotaConfigInAPIProduct para aplicar automáticamente la configuración de cuota de la operación del producto de API coincidente.

Agrega la siguiente política de cuota al PreFlow de solicitud después de la política de autenticación:

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

Donde AUTH_POLICY_STEP_NAME es el valor del atributo name en el elemento XML de la política de autenticación (VerifyAPIKey-1 o OAuthV2-VerifyAccessToken en los ejemplos de esta página). Debe coincidir con el atributo name de la política, no con el <DisplayName>.

Con esta configuración, cada operación de la herramienta tiene un límite de frecuencia independiente según la cuota definida en el producto de API. Por ejemplo, si tools/call/get_stock_price tiene una cuota de 300 por minuto y tools/call/get_company_news tiene una cuota de 3 por minuto, cada límite se aplica por separado, aunque se acceda a ambas herramientas a través del mismo proxy.

Completa la configuración del proxy

En el siguiente ejemplo, se muestra la configuración completa de PreFlow de la solicitud para un proxy de MCP con ParsePayload, autenticación de clave de API y aplicación de cuota por herramienta:

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

Filtrado de herramientas

Cuando un cliente envía una solicitud tools/list a través de un proxy de MCP con clave de API o autenticación de OAuth, Apigee filtra automáticamente la respuesta para incluir solo las herramientas registradas en el producto de API del cliente.

Por ejemplo, si el producto de API de un cliente incluye las operaciones tools/call/get_stock_price y tools/call/get_company_news, una respuesta tools/list del servidor de MCP se filtrará para devolver solo get_stock_price y get_company_news, incluso si el servidor de MCP expone herramientas adicionales.

Este filtrado se realiza de forma predeterminada cuando se aplica la siguiente configuración. No se requiere una política de filtrado específica:

  • El PreFlow de solicitud incluye ParsePayload y una política de autenticación (VerifyAPIKey o OAuthV2).
  • El producto de API incluye tools/list en payloadOperationGroup.
  • El producto de API especifica las operaciones de la herramienta (por ejemplo, tools/call/get_stock_price) a las que el cliente puede acceder.

Para probar el filtrado de herramientas, envía una solicitud de tools/list con la clave de API del cliente:

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

Si el producto de la API incluye tools/call/get_stock_price y tools/call/get_company_news, la respuesta filtrada se verá similar a la siguiente, incluso si el servidor de MCP expone herramientas adicionales:

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

Las herramientas que no se incluyen en el producto de API (por ejemplo, delete_account o admin_reset) se quitan automáticamente de la respuesta.

En la siguiente sesión de depuración, se muestra el paso McpToolsFilterExecution en el flujo de respuesta, con la propiedad mcp_flow_info.mcp.allowed.tools que enumera las herramientas permitidas por el producto de la API:

Sesión de depuración que muestra el paso McpToolsFilterExecution con mcp_flow_info.mcp.allowed.tools, en el que se enumeran las herramientas filtradas.

Usa flujos condicionales para la lógica por herramienta

Usa flujos condicionales cuando necesites lógica por herramienta más allá de lo que proporcionan las cuotas de productos de API, como aplicar tasas de SpikeArrest específicas de la herramienta, enrutar a diferentes backends o agregar transformaciones de solicitudes para herramientas específicas. Los flujos condicionales usan la variable de flujo parsepayload.policyName.operation para hacer coincidir la operación de MCP extraída.

Para una política ParsePayload llamada ParsePayload-MCP, haz lo siguiente:

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

Depura la configuración del proxy

Usa la herramienta Debug de Apigee para verificar que la política de ParsePayload extrae correctamente la operación de MCP y que las políticas de autenticación y de cuotas funcionan según lo previsto.

Sesión de depuración que muestra el paso ParsePayload-MCP con variables de flujo, incluida parsepayload.ParsePayload-MCP.operation establecida en tools/list.

En la sesión de depuración, verifica las siguientes variables de flujo después del paso de la política ParsePayload (en el que ParsePayload-MCP es el nombre de la política):

  • parsepayload.ParsePayload-MCP.operation: Debe contener el nombre completo de la operación (por ejemplo, tools/call/get_stock_price).
  • parsepayload.ParsePayload-MCP.json-rpc.request.method: Debe contener el método JSON-RPC (por ejemplo, tools/call).

Limitaciones

  • La política ParsePayload solo admite JSON-RPC-2.0 como tipo de carga útil.
  • Las operaciones de la herramienta de productos de API solo admiten los métodos tools/call y tools/list. El filtrado de herramientas para las respuestas de tools/list solo se aplica a las operaciones de tools/call configuradas en el producto de API.
  • La política ParsePayload analiza el cuerpo completo de la solicitud. Apigee aplica un límite predeterminado de 10 MB para el tamaño del cuerpo de la solicitud, que se puede configurar hasta 30 MB con la propiedad request.payload.parse.limit. Para obtener más información, consulta la referencia de propiedades de Endpoint.
  • La política ParsePayload con el protocolo de MCP solo analiza las cargas útiles de solicitudes JSON-RPC (que contienen los campos method y params). No se analizan las cargas útiles de las respuestas de MCP.
  • El filtrado de herramientas para las respuestas de tools/list requiere las políticas de ParsePayload y autenticación en el PreFlow de la solicitud.

¿Qué sigue?