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

APPLIES TO: Desenvolvedor | Básico | Básico v2 | Padrão | Standard v2 | Premium | Premium v2

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

O Gerenciamento de API do Azure também dá suporte à integração segura com servidores MCP compatíveis existentes - servidores de ferramentas hospedados fora do Gerenciamento de API. Para obter mais informações, confira Expor um servidor MCP existente.

Saiba mais sobre:

• Suporte a servidores MCP no Gerenciamento de API
• Funcionalidades do gateway de IA

Limitações

• Atualmente, o Gerenciamento de API dá suporte a ferramentas de servidor MCP, mas não dá suporte a recursos ou prompts do MCP.
• Atualmente, o Gerenciamento de API não dá suporte a recursos de servidor MCP em workspaces.

Pré-requisitos

• Se você ainda não tiver uma instância do Gerenciamento de API, conclua o seguinte início rápido: Criar uma instância do Gerenciamento de API do Azure. A instância deve estar em uma das camadas de serviço que dão suporte a servidores MCP.

• Verifique se sua instância gerencia uma API compatível com HTTP (qualquer API importada como uma API REST, incluindo APIs importadas de recursos do Azure) que você deseja expor como um servidor MCP. Para importar uma API de exemplo, consulte Importar e publicar sua primeira API.

  Observação

  Outros tipos de API no Gerenciamento de API que não são compatíveis com HTTP não podem ser expostos como servidores MCP.

• Se você habilitar o log de diagnóstico por meio do Application Insights ou do Azure Monitor no escopo global (todas as APIs) para a instância do serviço Gerenciamento de API, defina a configuração Número de bytes do payload a serem registrados em log para Resposta do Frontend como 0. Essa configuração impede o registro em log não intencional de corpos de resposta em todas as APIs e ajuda a garantir o funcionamento adequado dos servidores MCP. Para registrar payloads seletivamente em log para APIs específicas, defina a configuração individualmente no escopo da API, permitindo controle direcionado sobre o log de respostas.

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

Expor a API como um servidor MCP

Siga estas etapas para expor uma API REST gerenciada no Gerenciamento de API como um servidor MCP:

1. No portal do Azure, acesse sua instância de Gerenciamento de API.
2. No menu à esquerda, em APIs, selecione Servidores MCP>+ Criar servidor MCP.
3. Selecione Expor uma API como um servidor MCP.
4. Em Servidor MCP do back-end:
   1. Selecione uma API gerenciada para expor como um servidor MCP.
   2. 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.

      Observação

      Você pode atualizar as operações expostas como ferramentas posteriormente na lâmina Ferramentas do servidor MCP.

5. Em Novo servidor MCP:
   1. Insira um Nome para o servidor MCP no Gerenciamento de API.
   2. Opcionalmente, insira uma Descrição para o servidor MCP.
6. Selecione Criar.

• O servidor MCP é criado e as operações de API são expostas como ferramentas.
• O servidor MCP é listado na folha Servidores MCP. A coluna URL do Servidor mostra o ponto de extremidade do servidor MCP a ser chamado para teste ou em um aplicativo 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 se aplicam a todas as operações de API expostas como ferramentas no servidor MCP. Use essas políticas para controlar o acesso, a autenticação e outros aspectos das ferramentas.

Saiba mais sobre como configurar políticas:

• Políticas no Gerenciamento de API
• Transformar e proteger sua API
• Definir e editar políticas
• Acesso seguro ao servidor MCP

Cuidado

Não acesse o corpo da resposta usando a context.Response.Body variável nas políticas do servidor MCP. Isso dispara o buffer de resposta, que interfere no comportamento de streaming exigido pelos servidores MCP e pode causar um mau funcionamento.

Para configurar políticas para o servidor MCP, siga estas etapas:

1. No portal do Azure, acesse sua instância de Gerenciamento de API.

2. No menu à esquerda, em APIs, selecione Servidores MCP.

3. Selecione um servidor MCP da lista.

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

5. No editor de políticas, adicione ou edite as políticas que você deseja aplicar às ferramentas do servidor MCP. Defina as políticas no formato XML.

   Por exemplo, você pode adicionar uma política para limitar chamadas às ferramentas do servidor MCP (neste exemplo, uma chamada por 60 segundos por sessão MCP).

   <!-- Rate limit tool calls by Mcp-Session-Id header -->
   <set-variable name="body" value="@(context.Request.Body.As<string>(preserveContent: true))" />
   <choose>
       <when condition="@(
           Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"] != null 
           && Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"].ToString() == "tools/call"
       )">
       <rate-limit-by-key 
           calls="1" 
           renewal-period="60" 
           counter-key="@(
               context.Request.Headers.GetValueOrDefault("Mcp-Session-Id", "unknown")
           )" />
       </when>
   </choose>
   

   

Observação

O Gerenciamento de API avalia as políticas configuradas no escopo global (todas as APIs) antes de avaliar as políticas no escopo do servidor MCP.

Validar e usar o servidor MCP

Use um agente LLM em conformidade (como GitHub Copilot, Kernel Semântico ou Copilot Studio) ou um cliente de teste (como curl) para chamar o ponto de extremidade MCP hospedado no Gerenciamento de API. Verifique se a solicitação inclui os cabeçalhos ou tokens apropriados e confirme o roteamento e a resposta bem-sucedidos do servidor MCP.

Dica

Se você usar o Inspetor MCP para testar um servidor MCP gerenciado pelo Gerenciamento de API, use a versão 0.9.0.

Adicionar o servidor MCP no Visual Studio Code

No Visual Studio Code, use o chat do GitHub Copilot no modo de agente para adicionar o servidor MCP e usar as ferramentas. Para obter informações sobre servidores MCP no Visual Studio Code, confira Usar Servidores MCP no VS Code.

Para adicionar o servidor MCP no Visual Studio Code:

1. Use o comando MCP: Adicionar Servidor por meio da Paleta de Comandos.

2. Quando solicitado, selecione o tipo de servidor: HTTP (HTTP ou Eventos Enviados pelo Servidor).

3. Insira a URL do Servidor do servidor MCP no Gerenciamento de API. Por exemplo, https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp para o ponto de extremidade MCP.

4. Insira uma ID do Servidor de sua escolha.

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

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

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

   

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

Usar ferramentas no modo de agente

Após adicionar um servidor MCP no Visual Studio Code, você poderá usar ferramentas no modo de agente.

1. No chat do GitHub Copilot, selecione o modo Agente e selecione o botão Ferramentas para ver as ferramentas disponíveis.

   

2. Selecione uma ou mais ferramentas do servidor MCP para estar disponível 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.

   

Solução de problemas e problemas conhecidos

Problema	Causa	Solução
Erro 401 Unauthorized do back-end	Cabeçalho de autorização não encaminhado	Se necessário, utilize a política set-header para anexar o token manualmente
Chamada à API funciona no Gerenciamento de API, mas falha no agente	URL base incorreta ou token ausente	Verifique as políticas de segurança e o ponto de extremidade
Streaming do servidor MCP falha quando os logs de diagnóstico estão habilitados	O registro do corpo da resposta ou o acesso ao corpo da resposta por meio da política interfere no transporte MCP	Desabilite o log do corpo da resposta no escopo Todas as APIs - consulte Pré-requisitos

Conteúdo relacionado

• Exemplo: autorização de Servidores MCP com Metadados de Recurso Protegido (PRM)

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

• Laboratório de autorização do 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 no Centro de API do Azure

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

• Expor e controlar servidor MCP existente