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

APLICA-SE A: Developer | Basic | Basic v2 | Standard | Standard v2 | Premium | Premium v2

No API Management, pode expor uma API REST gerida na API Management como um servidor remoto Model Context Protocol (MCP ) usando o seu gateway de IA incorporado. Exponha uma ou mais das operações da API como ferramentas que os clientes MCP podem invocar usando o protocolo MCP.

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

Saiba mais sobre:

• Suporte ao servidor MCP no Gerenciamento de API
• Recursos de gateway de IA

Limitações

• Atualmente, a Gestão de APIs suporta ferramentas de servidor MCP, mas não suporta recursos ou prompts MCP.
• Atualmente, a Gestão de APIs não suporta capacidades de servidores MCP em espaços de trabalho.

Pré-requisitos

• Se você ainda não tiver uma instância de Gerenciamento de API, conclua o seguinte início rápido: Criar uma instância de Gerenciamento de API do Azure. A instância deve estar num dos níveis de serviço que suporta servidores MCP.

• Certifique-se de que a sua instância gere uma API compatível com HTTP (qualquer API importada como API REST, incluindo APIs importadas dos recursos Azure) que pretende expor como 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 ativar o registo de diagnóstico através do Application Insights ou Azure Monitor no âmbito global (todas as APIs) para a sua instância de serviço de gestão de APIs, defina o Número de bytes de payload a registar para a Resposta do Frontend a 0. Esta configuração previne o registo não intencional dos corpos de resposta em todas as APIs e ajuda a garantir o funcionamento adequado dos servidores MCP. Para registrar cargas úteis seletivamente para APIs específicas, configure o parâmetro individualmente no escopo da API, permitindo controlo específico sobre o registo de respostas.

• Para testar o servidor MCP, pode usar o Visual Studio Code com acesso ao GitHub Copilot ou a 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, vá para sua instância de Gerenciamento de API.
2. No menu à esquerda, em APIs, selecione MCP Servers>+ Create MCP server.
3. Selecione Expor uma API como um servidor MCP.
4. No servidor MCP de 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 folha Ferramentas do seu 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 da API são expostas como ferramentas.
• O servidor MCP está listado na folha Servidores MCP . A coluna URL do servidor mostra o ponto de extremidade do servidor MCP a ser chamado para teste ou dentro de 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 aplicam-se a todas as operações de API expostas como ferramentas no servidor MCP. Use estas políticas para controlar o acesso, autenticação e outros aspetos das ferramentas.

Saiba mais sobre como configurar políticas:

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

Atenção

Não acedas ao corpo da resposta usando a context.Response.Body variável dentro das políticas do servidor MCP. Ao fazê-lo, desencadeia o buffering de resposta, que interfere com o comportamento de streaming exigido pelos servidores MCP e pode causar avarias.

Para configurar políticas para o servidor MCP, siga estes passos:

1. No portal do Azure, vá para sua instância de Gerenciamento de API.

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

3. Selecione um servidor MCP na lista.

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

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

   Por exemplo, 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

A Gestão de APIs avalia as políticas configuradas no âmbito global (todas as APIs) antes de avaliar as políticas no âmbito do servidor MCP.

Validar e usar o servidor MCP

Use um agente LLM compatível (como GitHub Copilot, Semantic Kernel ou Copilot Studio) ou um cliente de teste (como curl) para chamar o ponto de extremidade MCP hospedado pelo Gerenciamento de API. Verifique se a solicitação inclui cabeçalhos ou tokens apropriados e confirme o roteamento e a resposta bem-sucedidos do servidor MCP.

Sugestão

Se usar o MCP Inspector para testar um servidor MCP gerido pela API Management, 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 básicas sobre servidores MCP no Visual Studio Code, consulte Usar servidores MCP no VS 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. Por exemplo, https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp para o endpoint 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 no Visual Studio Code, 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.

   

Resolução de problemas e problemas conhecidos

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

Conteúdo relacionado

• Exemplo: autorização de servidores MCP com metadados de recursos protegidos (PRM)

• Exemplo: 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

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

• Expor e controlar o servidor MCP existente