Expor e governar um servidor MCP existente

Este artigo mostra como usar o Gerenciamento de API para expor e governar um servidor MCP (Model Context Protocol) remoto existente - um servidor de ferramentas hospedado fora do Gerenciamento de API. Expor e governar as ferramentas do servidor através da API Management para que os clientes MCP possam chamá-las usando o protocolo MCP.

Os cenários de exemplo incluem:

Servidores de ferramentas Proxy LangChain ou LangServe através do Gerenciamento de API com autenticação por servidor e limites de taxa.
Exponha de forma segura ferramentas baseadas em Azure Logic Apps a copilotos usando filtragem IP e OAuth.
Centralize as ferramentas de servidor MCP do Azure Functions e os tempos de execução de código aberto no Centro de API do Azure.
Habilite o GitHub Copilot, Claude by Anthropic ou ChatGPT para interagir com segurança com ferramentas em toda a sua empresa.

O Gerenciamento de API também suporta servidores MCP expostos nativamente no Gerenciamento de API de APIs REST gerenciadas. Para obter mais informações, consulte Expor uma API REST como um servidor MCP.

Saiba mais sobre:

Limitações

O servidor MCP externo deve estar em conformidade com a versão 2025-06-18 MCP ou posterior. O servidor pode suportar:
- Ou sem autorização, ou protocolos de autorização que cumpram os seguintes padrões: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#standards-compliance.
- Tipos de transporte HTTP ou SSE que suportam transmissão contínua.
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.
Acesso a um servidor externo compatível com MCP (por exemplo, hospedado em Aplicativos Lógicos do Azure, Azure Functions, LangServe ou outras plataformas).
Credenciais apropriadas para o servidor MCP (como credenciais de cliente OAuth 2.0 ou chaves de API, dependendo do servidor) para acesso seguro.
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 Gestão de APIs, defina o Número de bytes de carga 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, use Visual Studio Code com acesso ao GitHub Copilot ou a uma ferramenta como o MCP Inspector.

Expor um servidor MCP existente

Siga estes passos para expor um servidor MCP existente na Gestão de API:

No portal do Azure, vá para sua instância de Gerenciamento de API.
No menu à esquerda, em APIs, selecione Servidores> MCP+ Criar servidor MCP.
Selecione Expor um servidor MCP existente.
No servidor MCP de back-end:
1. Insira a URL base do servidor MCP existente. Por exemplo, https://learn.microsoft.com/api/mcp para o servidor Microsoft Learn MCP.
2. No tipo Transporte, HTTP Streamable é selecionado por defeito.
Em Novo servidor MCP:
1. Introduza um nome para o servidor MCP na API Management.
2. Em Caminho base, insira um prefixo de rota para ferramentas. Por exemplo, mytools.
3. Opcionalmente, insira uma Descrição para o servidor MCP.
Selecione Criar.

Captura de ecrã da criação de um servidor MCP no portal.

O servidor MCP é criado e as operações do servidor remoto são expostas como ferramentas.
O servidor MCP está listado no painel Servidores MCP . A coluna URL do servidor mostra a URL do servidor MCP a ser chamada para teste ou dentro de um aplicativo cliente.

Importante

Atualmente, o Gerenciamento de API não exibe ferramentas do servidor MCP existente. Deve registar e configurar todas as ferramentas no servidor MCP remoto existente.

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:

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:

No portal do Azure, vá para sua instância de Gerenciamento de API.
No menu à esquerda, em APIs, selecione Servidores MCP.
Selecione um servidor MCP na lista.
No menu à esquerda, em MCP, selecione Políticas.

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:

Use o comando MCP: Add Server da Paleta de Comandos.
Quando solicitado, selecione o tipo de servidor: HTTP (HTTP ou Server Sent Events).
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.
Insira um ID de servidor de sua escolha.
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

Captura de tela da configuração do cabeçalho de autenticação para um servidor MCP

Usar ferramentas no modo de agente

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

No bate-papo do GitHub Copilot, selecione Modo de agente e selecione o botão Ferramentas para ver as ferramentas disponíveis.
Selecione uma ou mais ferramentas do servidor MCP para estarem disponíveis no chat.
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

Comentários

Esta página foi útil?

Last updated on 2025-11-19