Expor e controlar um servidor MCP existente

Este artigo mostra como usar o Gerenciamento de API para expor e controlar um servidor remoto Model Context Protocol (MCP) existente - um servidor de ferramentas hospedado fora do Gerenciamento de API. Exponha e governe as ferramentas do servidor por meio do Gerenciamento de API para que os clientes MCP possam chamá-las usando o protocolo MCP.

Alguns cenários de exemplo incluem:

Proxy de servidores de ferramentas LangChain ou LangServe por meio do Gerenciamento de API com autenticação por servidor e limites de taxa.
Exponha com segurança ferramentas baseadas em Aplicativos Lógicos do Azure para copilots usando filtragem de IP e OAuth.
Centralizar ferramentas de servidor MCP do Azure Functions e de runtimes de código aberto no Centro de API do Azure.
Habilitar o GitHub Copilot, Claude by Anthropic ou ChatGPT para interagir com segurança com ferramentas em toda a empresa.

O Gerenciamento de API também dá suporte a servidores MCP expostos nativamente no Gerenciamento de API a partir de APIs REST gerenciadas. Para obter mais informações, confira Expor uma API REST como servidor MCP.

Saiba mais sobre:

Limitações

O servidor MCP externo deve estar em conformidade com a versão 2025-06-18 ou posterior do MCP. O servidor pode dar suporte a:
- Nenhuma autorização ou protocolos de autorização que estejam em conformidade com os seguintes padrões: https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization#standards-compliance.
- Tipos de transporte HTTP ou SSE que podem ser transmitidos.
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.
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 você habilitar o registro em log de diagnóstico por meio do Application Insights ou do Azure Monitor no escopo global (todas as APIs) para a instância do Gerenciamento de API, defina a configuração Número de bytes de payload a serem registrados 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, use o Visual Studio Code com acesso ao GitHub Copilot ou a uma ferramenta como o MCP Inspector.

Expor um servidor MCP existente

Siga estas etapas para expor um servidor MCP existente no Gerenciamento de API:

No portal do Azure, acesse sua instância de Gerenciamento de API.
No menu à esquerda, em APIs, selecione Servidores MCP>+ Criar servidor MCP.
Selecione Expor um servidor MCP existente.
Em 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 MCP do Microsoft Learn.
2. No tipo de transporte, HTTP transmissível é selecionado por padrão.
Em Novo servidor MCP:
1. Insira um nome para o servidor MCP no Gerenciamento de API.
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 tela 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. Você deve registrar 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 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 a configuração de políticas:

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:

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

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, Semantic Kernel 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 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 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:

Use o comando MCP: Adicionar Servidor por meio da Paleta de Comandos.
Quando solicitado, selecione o tipo de servidor: HTTP (HTTP ou Eventos Enviados pelo Servidor).
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.
Insira uma ID do Servidor de sua escolha.
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

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

Usar ferramentas no modo de agente

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

No chat do GitHub Copilot, selecione o modo Agente e selecione o botão Ferramentas para ver as ferramentas disponíveis.
Selecione uma ou mais ferramentas do servidor MCP para estar disponível 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.

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 em log do corpo da resposta ou o acesso ao corpo da resposta por meio da política interfere no transporte MCP	Desabilite o registro em log 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