Expor a API REST no Gerenciamento de API como um servidor MCP

APLICA-SE A: BÁSICO | Padrão | Prémio

No Gerenciamento de API, você pode expor uma API REST gerenciada no Gerenciamento de API como um servidor MCP (Model Context Protocol) remoto. Exponha uma ou mais operações de API como ferramentas que os clientes MCP podem chamar usando o protocolo MCP.

O uso do Gerenciamento de API para expor servidores MCP remotos fornece controle centralizado sobre autenticação, autorização e monitoramento. Ele simplifica o processo de exposição de APIs como servidores MCP, ajudando a mitigar riscos comuns de segurança e garantindo escalabilidade.

Importante

Este recurso está a ser introduzido em pré-visualização nas camadas clássicas Basic, Standard e Premium. Ele está sendo lançado primeiro para o grupo de atualizaçãoantecipada do AI Gateway. Depois de entrar no grupo, pode levar 2 horas para acessar os recursos do servidor MCP.

Neste artigo, você aprenderá a:

• Expor uma API REST no Gerenciamento de API como um servidor MCP
• Configurar políticas para o servidor MCP
• Testar o servidor MCP gerado a partir de um cliente MCP

Sobre os servidores MCP

Os agentes de IA estão se tornando amplamente adotados por causa dos recursos aprimorados de modelo de linguagem grande (LLM). No entanto, mesmo os modelos mais avançados enfrentam limitações devido ao seu isolamento de dados externos. Cada nova fonte de dados potencialmente requer implementações personalizadas para extrair, preparar e tornar os dados acessíveis para os modelos.

O protocolo de contexto de modelo (MCP) ajuda a resolver esse problema. O MCP é um padrão aberto para conectar modelos e agentes de IA com fontes de dados externas, como fontes de dados locais (bancos de dados ou arquivos de computador) ou serviços remotos (sistemas disponíveis na internet, como bancos de dados remotos ou APIs).

Arquitetura MCP

O diagrama a seguir ilustra a arquitetura MCP:

A arquitetura é composta pelos seguintes componentes:

Componente	Descrição
Anfitriões MCP	Aplicativos LLM, como aplicativos de bate-papo ou assistentes de IA em seus IDEs (como o GitHub Copilot no Visual Studio Code) que precisam acessar recursos externos
Clientes MCP	Clientes de protocolo, dentro do aplicativo host, que mantêm conexões 1:1 com servidores
Servidores MCP	Programas leves que expõem recursos específicos e fornecem contexto, ferramentas e prompts aos clientes
Protocolo MCP	Camada de transporte no meio

O MCP segue uma arquitetura cliente-servidor em que um aplicativo host pode se conectar a vários servidores. Sempre que seu host ou cliente MCP precisar de uma ferramenta, ele se conecta ao servidor MCP. Em seguida, o servidor MCP se conecta, por exemplo, a um banco de dados ou a uma API. Os anfitriões e servidores MCP ligam-se uns aos outros através do protocolo MCP.

Servidores MCP remotos versus locais

O MCP utiliza uma arquitetura cliente-host-servidor construída no JSON-RPC 2.0 para mensagens. A comunicação entre clientes e servidores ocorre em camadas de transporte definidas e suporta principalmente dois modos de operação:

• Servidores MCP remotos - os clientes MCP se conectam aos servidores MCP pela Internet, estabelecendo uma conexão usando HTTP e eventos enviados pelo servidor (SSE) e autorizando o acesso do cliente MCP aos recursos na conta do usuário usando OAuth.

• Servidores MCP locais Os clientes MCP se conectam a servidores MCP na mesma máquina, usando entrada/saída padrão como um método de transporte local.

Pré-requisitos

• Conclua a instrução de início rápido seguinte: Criar uma instância da Gestão de APIs do Azure. Atualmente, apenas as camadas Premium, Standard e Basic do Gerenciamento de API suportam servidores MCP.
• Certifique-se de que sua instância gerencie uma API REST que você gostaria de expor como um servidor MCP. Para importar uma API de exemplo, consulte Importar e publicar sua primeira API.

  Observação

  Somente APIs HTTP do Gerenciamento de API podem ser expostas como servidores MCP.

• Para testar o servidor MCP, você pode usar o Visual Studio Code com acesso ao GitHub Copilot.

Expor a API como um servidor MCP

1. No portal do Azure, acesse a visualização do servidor MCP na seguinte URL. A visualização pode ser usada apenas nos níveis suportados de gerenciamento de API.

   https://portal.azure.com/?Microsoft_Azure_ApiManagement=mcp
   

2. Navegue até sua instância de Gerenciamento de API.

3. No menu à esquerda, selecione APIs>MCP Servers>+ Create new MCP Server.

4. Em API, selecione uma API REST para expor como um servidor MCP.

5. Selecione uma ou mais operações de API para expor como ferramentas. Você pode selecionar todas as operações ou apenas operações específicas.

6. Selecione Criar.

O servidor MCP é criado e as operações da API são expostas como ferramentas. O servidor MCP está listado no painel Servidores MCP . A coluna URL mostra o endpoint do servidor MCP que pode ser chamado para teste ou numa aplicação cliente.

Configurar políticas para o servidor MCP

Configure uma ou mais políticas de Gerenciamento de API para ajudar a gerenciar o servidor MCP. As políticas são aplicadas a todas as operações de API expostas como ferramentas no servidor MCP e podem ser usadas para controlar o acesso, a autenticação e outros aspetos das ferramentas.

Para obter um tutorial sobre como configurar políticas, consulte Transformar e proteger sua API.

Para configurar políticas para o servidor MCP:

1. No portal, em APIs, selecione Servidores MCP.

2. Selecione o servidor MCP que você criou.

3. No menu à esquerda, em MCP, selecione Políticas.

4. No editor de políticas, adicione ou edite as políticas que deseja aplicar às ferramentas do servidor MCP. As políticas são definidas em formato XML. Por exemplo, você pode adicionar uma política para limitar chamadas às ferramentas do servidor MCP (neste exemplo, 5 chamadas por 30 segundos por endereço IP do cliente).

    <rate-limit-by-key calls="5" renewal-period="30" counter-key="@(context.Request.IpAddress)" remaining-calls-variable-name="remainingCallsPerIP" />
   

   

Testar e usar o servidor MCP

Para verificar se o servidor MCP está funcionando, você pode usar o Visual Studio Code para enviar solicitações para as ferramentas de servidor MCP.

No Visual Studio Code, use o chat do GitHub Copilot no modo de agente (visualização) para adicionar o servidor MCP e usar as ferramentas. Para obter informações básicas sobre servidores MCP no Visual Studio Code, consulte Usar servidores MCP no VS Code (visualização).

Sugestão

Se você usar o Inspetor MCP para testar um servidor MCP criado pelo Gerenciamento de API, recomendamos o uso da versão 0.9.0.

Adicionar o servidor MCP no Visual Studio Code

Para adicionar o servidor MCP no Visual Studio Code:

1. Use o comando MCP: Add Server da Paleta de Comandos.

2. Quando solicitado, selecione o tipo de servidor: HTTP (HTTP ou Server Sent Events).

3. Insira a URL do servidor MCP em Gerenciamento de API. Exemplo: https://<apim-service-name>.azure-api.net/<api-name>-mcp/sse (para o ponto de extremidade SSE) ou https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp (para o ponto de extremidade MCP)

4. Insira um ID de servidor de sua escolha.

5. Selecione se deseja salvar a configuração nas configurações do espaço de trabalho ou nas configurações do usuário.

   • Configurações do espaço de trabalho - A configuração do servidor é salva em um .vscode/mcp.json arquivo disponível apenas no espaço de trabalho atual.

   • Configurações do usuário - A configuração do servidor é adicionada ao seu arquivo global settings.json e está disponível em todos os espaços de trabalho. A configuração é semelhante à seguinte:

   

Adicione campos à configuração JSON para definições como cabeçalho de autenticação. O exemplo a seguir mostra a configuração de uma chave de subscrição do Gerenciamento de API passada num cabeçalho como um valor de entrada. Saiba mais sobre o formato de configuração

Usar ferramentas no modo de agente

Depois de adicionar um servidor MCP, você pode usar ferramentas no modo de agente.

1. No bate-papo do GitHub Copilot, selecione Modo de agente e selecione o botão Ferramentas para ver as ferramentas disponíveis.

   

2. Selecione uma ou mais ferramentas do servidor MCP para estarem disponíveis no chat.

   

3. Insira um prompt no chat para invocar a ferramenta. Por exemplo, se você selecionou uma ferramenta para obter informações sobre um pedido, poderá perguntar ao agente sobre um pedido.

   Get information for order 2
   

   Selecione Continuar para ver os resultados. O agente usa a ferramenta para chamar o servidor MCP e retorna os resultados no chat.

   

Conteúdo relacionado

• Exemplo de Python: Proteger servidores MCP remotos usando o Gerenciamento de API do Azure (experimental)

• Laboratório de autorização de cliente MCP

• Usar a extensão de Gerenciamento de API do Azure para VS Code para importar e gerenciar APIs

• Registrar e descobrir servidores MCP remotos na Central de APIs do Azure