O Google usa tecnologia de IA na tradução de conteúdos para seu idioma de preferência. As traduções com IA podem ter erros.

Gerenciar o acesso às ferramentas do MCP com produtos de API

Esta página se aplica à Apigee e à Apigee híbrida.

Confira a documentação da Apigee Edge.

Nesta página, descrevemos como usar produtos de API da Apigee para controlar o acesso às ferramentas do MCP. Se você usa o proxy de descoberta do MCP da Apigee ou o tráfego de proxy para seu próprio servidor MCP, é possível autenticar clientes do MCP, aplicar cotas por ferramenta e filtrar a visibilidade da ferramenta com base na configuração do produto de API.

Os servidores MCP usam um único endpoint (por exemplo, /mcp) para todas as invocações de ferramentas. Ao contrário das APIs REST, em que as operações são diferenciadas por caminho de URL e método HTTP, o MCP incorpora a operação no corpo da solicitação JSON-RPC. A Apigee usa a política ParsePayload para extrair essas operações. Assim, as políticas padrão de gerenciamento de APIs (autenticação, aplicação de cotas e filtragem de ferramentas) podem ser aplicadas por ferramenta.

Visão geral

Para gerenciar o acesso à ferramenta MCP com produtos de API, siga estas etapas:

Adicione a política ParsePayload para extrair o nome da ferramenta MCP do corpo da solicitação.
Configure um produto de API com operações de ferramentas do MCP e cotas por ferramenta.
Registre um app de desenvolvedor para receber credenciais do cliente.
Adicione políticas de autenticação (chave de API ou OAuth 2.0) para verificar as credenciais do cliente em relação ao produto da API.
Adicione uma política de cota para aplicar limites de taxa por ferramenta.
Filtragem da ferramenta de teste para confirmar que as respostas tools/list são filtradas com base na configuração do produto da API.

Adicionar a política ParsePayload

A política ParsePayload analisa o corpo da solicitação JSON-RPC e extrai a operação do MCP, como tools/call/get_weather ou tools/list. A operação extraída é armazenada em uma variável de fluxo prefixada com o nome da política (por exemplo, parsepayload.ParsePayload-MCP.operation), que as políticas downstream usam para autenticação e aplicação de cotas.

Adicione a seguinte política ParsePayload ao pré-fluxo de solicitação do proxy MCP:

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

Em que:

<Source>: a mensagem a ser analisada. O padrão é request.
<PayloadType>: o formato do payload. Precisa ser JSON-RPC-2.0.
<Protocol>: o protocolo a ser usado para análise. Precisa ser MCP para servidores MCP.

Após a execução, a política preenche variáveis de fluxo prefixadas com o nome da instância da política, seguindo o padrão parsepayload.policyName.suffix. Para uma política chamada ParsePayload-MCP, as seguintes variáveis são definidas:

Variável de fluxo	Descrição	Valor de exemplo
`parsepayload.ParsePayload-MCP.operation`	O nome da operação derivada usado para correspondência de produtos de API e aplicação de cota.	`tools/call/get_weather`
`parsepayload.ParsePayload-MCP.json-rpc.request.method`	O campo `method` JSON-RPC da solicitação.	`tools/call`
`parsepayload.ParsePayload-MCP.json-rpc.request.id`	O campo `id` JSON-RPC da solicitação.	`1`
`parsepayload.ParsePayload-MCP.json-rpc.request.params.name`	O campo `params.name` da solicitação.	`get_weather`

Configurar um produto de API com operações de ferramentas do MCP

Um produto de API define quais ferramentas do MCP um aplicativo cliente pode acessar e os limites de cota para cada ferramenta. Você configura as operações da ferramenta MCP usando o campo payloadOperationGroup na definição do produto de API.

Cada entrada em payloadOperationGroup.operationConfigs especifica:

O proxy de API que atende às ferramentas do MCP (apiSource).
Uma ou mais operações de ferramenta (por exemplo, tools/call/get_stock_price, tools/list).
Uma cota opcional para esse conjunto de operações.

A UI de criação de produtos de API mostrando o painel "Operação de payload" com o proxy de API definido como mcp-discovery, o protocolo definido como MCP e as opções de tipo de operação do MCP para "List" e "Call" com configuração de cota.

Use a seguinte chamada de API para criar um produto de API com operações da ferramenta 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"
          }
        }
      ]
    }
  }'

Em que:

ORG_NAME é o nome da organização da Apigee;
PRODUCT_NAME é o nome interno do produto de API.
PRODUCT_DISPLAY_NAME é o nome de exibição do produto de API.
MCP_PROXY_NAME é o nome do proxy de API que encaminha o tráfego para o servidor MCP. Pode ser um proxy de descoberta do MCP da Apigee ou um proxy com seu próprio servidor MCP como back-end.

Configurar cotas por ferramenta

É possível configurar cotas diferentes para ferramentas individuais. Por exemplo, a configuração a seguir limita get_stock_price a 300 chamadas por minuto, mas restringe get_company_news a apenas 3 chamadas 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" }
      }
    ]
  }
}

Observação:inclua tools/list como uma operação no produto de API se quiser que o cliente possa descobrir as ferramentas disponíveis. Se tools/list não for incluído, o cliente não poderá listar ferramentas usando esse produto da API.

É possível criar vários produtos de API com diferentes subconjuntos de ferramentas para oferecer acesso em níveis. Por exemplo, um produto Básico pode incluir apenas tools/call/get_stock_price, enquanto um produto Premium inclui todas as ferramentas disponíveis com cotas mais altas. Cada app de desenvolvedor está associado a um ou mais produtos de API. Assim, diferentes clientes recebem acesso automático a diferentes conjuntos de ferramentas com limites de taxa independentes.

Registre um app de desenvolvedor

Para receber uma chave de API ou credenciais OAuth para teste, registre um desenvolvedor e crie um app para desenvolvedores associado ao produto de API criado na etapa anterior.

Registre um desenvolvedor de apps na sua organização da Apigee.
Crie um app de desenvolvedor e associe-o ao seu produto de API.
Obtenha o token do cliente (chave de API) nas credenciais do app. Use essa chave nos exemplos de autenticação a seguir.

Adicionar políticas de autenticação

Depois de adicionar a política ParsePayload, adicione uma política de autenticação para verificar se o cliente está autorizado a usar a ferramenta do MCP solicitada. O Apigee compara a operação extraída com as operações definidas no produto de API do cliente.

Se a ferramenta solicitada não estiver listada no produto de API do cliente, o Apigee retornará um erro 401 Unauthorized.

Opção 1: autenticação de chave de API

Use a política VerifyAPIKey para autenticar clientes usando uma chave de API. Adicione esta política ao PreFlow de solicitação após a política ParsePayload:

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

O cliente transmite a chave de API como um parâmetro de consulta ao chamar o proxy do 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
  }'

Também é possível configurar a política para ler a chave de API de um cabeçalho:

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

Opção 2: autenticação do OAuth 2.0

Use a política OAuthV2 com a operação VerifyAccessToken para autenticar clientes usando tokens de acesso do OAuth 2.0. Adicione essa política ao PreFlow de solicitação após a política ParsePayload:

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

O cliente transmite o token de acesso no cabeçalho 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
  }'

Para mais informações sobre como configurar o OAuth 2.0 na Apigee, consulte Como começar a usar o OAuth2.

adicionar uma política Quota

Adicione uma política de Quota para aplicar os limites de taxa por ferramenta definidos no produto de API. A política usa UseQuotaConfigInAPIProduct para aplicar automaticamente a configuração de cota da operação correspondente do produto de API.

Adicione a seguinte política de cota ao PreFlow de solicitação após a política de autenticação:

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

Em que AUTH_POLICY_STEP_NAME é o valor do atributo name no elemento XML da política de autenticação (VerifyAPIKey-1 ou OAuthV2-VerifyAccessToken nos exemplos desta página). Ele precisa corresponder ao atributo name da política, não ao <DisplayName>.

Com essa configuração, cada operação da ferramenta tem a taxa limitada de forma independente de acordo com a cota definida no produto da API. Por exemplo, se tools/call/get_stock_price tiver uma cota de 300 por minuto e tools/call/get_company_news tiver uma cota de 3 por minuto, cada limite será aplicado separadamente, mesmo que as duas ferramentas sejam acessadas pelo mesmo proxy.

Concluir a configuração de proxy

O exemplo a seguir mostra a configuração completa do PreFlow de solicitação para um proxy do MCP com ParsePayload, autenticação de chave de API e aplicação de cota por ferramenta:

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

Filtragem de ferramentas

Quando um cliente envia uma solicitação tools/list por um proxy do MCP com chave de API ou autenticação OAuth, o Apigee filtra automaticamente a resposta para incluir apenas as ferramentas registradas no produto de API do cliente.

Por exemplo, se o produto de API de um cliente incluir as operações tools/call/get_stock_price e tools/call/get_company_news, uma resposta tools/list do servidor MCP será filtrada para retornar apenas get_stock_price e get_company_news, mesmo que o servidor MCP exponha outras ferramentas.

Essa filtragem acontece por padrão quando a seguinte configuração está em vigor. Não é necessário ter uma política de filtragem dedicada:

O PreFlow de solicitação inclui o ParsePayload e uma política de autenticação (VerifyAPIKey ou OAuthV2).
O produto da API inclui tools/list no payloadOperationGroup.
O produto de API especifica as operações da ferramenta (por exemplo, tools/call/get_stock_price) que o cliente pode acessar.

Para testar a filtragem de ferramentas, envie uma solicitação tools/list com a chave de API do 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
  }'

Se o produto da API incluir tools/call/get_stock_price e tools/call/get_company_news, a resposta filtrada será semelhante à seguinte, mesmo que o servidor MCP exponha outras ferramentas:

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

As ferramentas que não estão listadas no produto de API (por exemplo, delete_account ou admin_reset) são removidas automaticamente da resposta.

A sessão de depuração a seguir mostra a etapa McpToolsFilterExecution no fluxo de resposta, com a propriedade mcp_flow_info.mcp.allowed.tools listando as ferramentas permitidas pelo produto de API:

Sessão de depuração mostrando a etapa McpToolsFilterExecution com mcp_flow_info.mcp.allowed.tools listando as ferramentas filtradas.

Usar fluxos condicionais para lógica por ferramenta

Use fluxos condicionais quando precisar de uma lógica por ferramenta além do que as cotas de produtos de API oferecem, como aplicar taxas de SpikeArrest específicas da ferramenta, rotear para diferentes back-ends ou adicionar transformações de solicitação para ferramentas específicas. Os fluxos condicionais usam a variável de fluxo parsepayload.policyName.operation para corresponder à operação extraída da MCP.

Para uma política ParsePayload chamada 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>

Depurar a configuração de proxy

Use a ferramenta Debug da Apigee para verificar se a política ParsePayload está extraindo corretamente a operação do MCP e se as políticas de autenticação e de cota estão funcionando conforme o esperado.

Sessão de depuração mostrando a etapa ParsePayload-MCP com variáveis de fluxo, incluindo parsepayload.ParsePayload-MCP.operation definido como tools/list.

Na sessão de depuração, verifique as seguintes variáveis de fluxo após a etapa da política ParsePayload (em que ParsePayload-MCP é o nome da política):

parsepayload.ParsePayload-MCP.operation: precisa conter o nome completo da operação (por exemplo, tools/call/get_stock_price).
parsepayload.ParsePayload-MCP.json-rpc.request.method: precisa conter o método JSON-RPC (por exemplo, tools/call).

Limitações

A política ParsePayload é compatível apenas com JSON-RPC-2.0 como tipo de payload.
As operações da ferramenta de produto de API são compatíveis apenas com os métodos tools/call e tools/list. A filtragem de ferramentas para respostas de tools/list só se aplica a operações de tools/call configuradas no produto de API.
A política ParsePayload analisa todo o corpo da solicitação. A Apigee aplica um limite padrão de tamanho do corpo da solicitação de 10 MB, que pode ser configurado até 30 MB usando a propriedade request.payload.parse.limit. Para mais detalhes, consulte a Referência de propriedades do endpoint.
A política ParsePayload com protocolo MCP analisa apenas payloads de solicitação JSON-RPC (que contêm campos method e params). Os payloads de resposta do MCP não são analisados.
A filtragem de ferramentas para respostas tools/list exige as políticas de ParsePayload e autenticação no PreFlow da solicitação.

A seguir

Saiba mais sobre o MCP na Apigee em Visão geral do MCP na Apigee.
Comece a usar proxies do MCP em Começar a usar a Apigee e o MCP.
Saiba mais sobre produtos de API e como gerenciar produtos de API.
Saiba mais sobre a limitação de taxa na Apigee.
Saiba mais sobre chaves de API e autenticação OAuth 2.0.