Azure AI Gateway MCP — Casos de uso, Instalar & Demo ao vivo

Por que usar

Principais recursos

APIM na frente dos servidores Azure OpenAI / MCP como camada de governança
Cotas de token por assinatura, por modelo, por equipe
Cache de completions determinísticas para reduzir gastos
Balanceamento de carga + failover em múltiplas regiões AOAI
Logging completo de requisição/resposta para App Insights para auditoria

Demo ao vivo

Como fica na prática

azure-ai-gateway.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "azure-ai-gateway": {
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "azure-ai-gateway",
      "command": "uvx",
      "args": [
        "azure-ai-gateway-mcp"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "azure-ai-gateway": {
      "command": {
        "path": "uvx",
        "args": [
          "azure-ai-gateway-mcp"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add azure-ai-gateway -- uvx azure-ai-gateway-mcp

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Azure AI Gateway

Aplicar cotas de token por equipe em deployments do Azure OpenAI

👤 Equipes de plataforma central governando gastos com LLM ⏱ ~30 min advanced

Quando usar: Múltiplas equipes de produto compartilham AOAI; um loop descontrolado de uma equipe não deve queimar o orçamento TPM compartilhado.

Pré-requisitos

Instância APIM com padrões AI-Gateway aplicados — Implante a arquitetura de referência do repositório Azure-Samples/AI-Gateway
Chave de assinatura APIM por equipe — Cada equipe obtém uma assinatura APIM distinta (chave) que inclui no cabeçalho Ocp-Apim-Subscription-Key

Fluxo

Revisar cotas atuais

Liste assinaturas APIM com suas cotas TPM e RPM atuais para o produto AOAI.✓ Copiado

→ Tabela de cota por equipe
Ajustar uma equipe ruidosa para baixo

A equipe 'growth' está em 90% de queima de TPM diariamente. Reduza sua cota de 200k → 100k TPM. Mantenha outras inalteradas.✓ Copiado

→ Cota atualizada; confirmação
Monitorar após a mudança

Na próxima hora, puxe contagens 429 (limitadas por taxa) por assinatura. Confirme que growth está sendo controlado, mas as equipes críticas de produção não são afetadas.✓ Copiado

→ Aplicação visível em métricas

Resultado: Gasto compartilhado AOAI controlado sem destruir tráfego legítimo de alta prioridade.

Armadilhas

Definir cotas muito baixas priva cargas de trabalho legítimas — Implante em modo shadow primeiro (somente log), depois aplique quando você entender os padrões reais

Configurar failover multi-região para um deployment do Azure OpenAI

👤 SREs executando cargas de trabalho de AI em produção ⏱ ~45 min advanced

Quando usar: Uma indisponibilidade AOAI regional (rara mas real) deve fazer failover transparentemente para outra região.

Pré-requisitos

Deployments AOAI em ≥2 regiões (ex: East US, West Europe) — Provisione via portal Azure; combine modelo + versão

Fluxo

Inspecionar pool de backend atual

Mostre o pool de backend APIM para nossa API AOAI. Quantos backends, prioridade, configuração de circuit-breaker?✓ Copiado

→ Configuração de pool atual
Adicionar região secundária

Adicione o endpoint West Europe AOAI como priority=2 com circuit-breaker: 5 falhas em 1 min → aberto por 5 min. Mantenha East US como primário.✓ Copiado

→ Pool atualizado, 2 backends configurados
Testar failover

Simule indisponibilidade primária desabilitando o backend East US por 2 min. Confirme que o tráfego muda para West Europe, depois faça rollback.✓ Copiado

→ Mudança de tráfego observada; rollback verificado

Resultado: Failover transparente com evidência de que funciona antes de você precisar.

Armadilhas

Diferentes regiões têm versões diferentes de modelos implantadas — Fixe uma versão de modelo que exista em ambas as regiões; versões incompatíveis silenciosamente retornam qualidade diferente

Implantar cache semântico para reduzir custos de repetição de prompt

👤 Equipes de plataforma conscientes de custos ⏱ ~30 min advanced

Quando usar: Seus usuários fazem perguntas semelhantes repetidamente; 30–60% das chamadas são efetivamente cache hits.

Fluxo

Ativar política de cache semântico

Ative a política semantic-cache-lookup do APIM na API AOAI completions com limiar de similaridade 0.95, TTL 1h.✓ Copiado

→ Política aplicada
Observar taxa de acerto

Após 24h, puxe a taxa de cache hit e economia de tokens do App Insights.✓ Copiado

→ Taxa de acerto % + tokens economizados
Ajustar limiar

Se a taxa de acerto <20%, baixe o limiar para 0.92 e observe novamente. Se houver reclamações de qualidade, aumente para 0.97.✓ Copiado

→ Ajuste iterativo com medições

Resultado: Economia de custos mensurada em consultas repetidas sem degradar a qualidade de saída.

Armadilhas

Cache muito agressivo serve respostas erradas para perguntas semelhantes mas diferentes — Comece alto (0.97) e só reduza com base na qualidade observada

Combinações

Combine com outros MCPs para 10× de alavancagem

azure-ai-gateway + sentry

Correlacionar picos 5xx do APIM com erros do lado da aplicação

Se Sentry mostra pico 5xx no app X às 10:02, puxe métricas APIM para a mesma janela e identifique se o gateway causou.✓ Copiado

azure-ai-gateway + notion

Relatório semanal de governança de tráfego de AI para Notion

Compile uso de TPM por equipe para a semana, contagens 429, taxa de cache hit; poste como página Notion.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_subscriptions	product_id?	Inventariar equipes consumindo o gateway	gratuito (chamada ARM API)
update_quota	subscription_id, tpm?, rpm?	Ajustar limites de token/requisição de uma equipe	gratuito
get_backend_pool	api_id	Inspecionar configuração de roteamento e failover	gratuito
update_backend_pool	api_id, backends, policies	Mudar prioridades, circuit breakers, balanceamento de carga	gratuito
apply_policy	api_id, policy_xml	Implantar política APIM (cache, autenticação, logging)	gratuito
get_metrics	api_id, since, until	Observar forma do tráfego por API	gratuito

Custo e limites

O que custa rodar

Cota de API: Limites de taxa do Azure Resource Manager (generosos por tenant)
Tokens por chamada: Leituras de policy/pool de backend: 500–2000 tokens
Monetário: Preço APIM começa em ~$40/mês (tier Basic); tier Standard recomendado para prod
Dica: Cache semântico geralmente compensa o custo do APIM muitas vezes se seu tráfego se repete. Meça a taxa de acerto para justificar.

Segurança

Permissões, segredos, alcance

Escopos mínimos: APIM Contributor na instância APIM alvo

Armazenamento de credenciais: Credenciais de service principal Azure (client id/secret/tenant) em env

Saída de dados: Chamadas da ARM API para management.azure.com; corpos de prompt/response atravessam o APIM

Nunca conceda: Owner na assinatura Global admin

O repositório AI-Gateway é código de referência/amostra; revise antes de implantar literalmente em produção.
Logging de requisição/resposta pode capturar PII — mascare na política antes de enviar para App Insights.

Solução de problemas

Erros comuns e correções

401 em chamadas da ARM API

Service principal não tem a função APIM Contributor no grupo de recursos. Conceda via portal ou az cli.

Verificar: az role assignment list --assignee <sp>

Falha na aplicação de política — erro de validação XML

XML de política APIM é rigoroso; use o editor de política do portal para validar, depois copie e cole.

429s persistem após aumentar cota TPM

O deployment AOAI subjacente pode ser o gargalo. Verifique TPM de deployment, não apenas TPM de assinatura APIM.

Taxa de cache hit semântico é 0%

Backend de embedding para cache-lookup não configurado; verifique a referência de embeddings da política de cache.

Alternativas

Azure AI Gateway vs. outros

Alternativa	Quando usar	Troca
Cloudflare AI Gateway	Você está na Cloudflare e quer roteamento LLM multi-provider pronto	Integração menos profunda com modelos hospedados em Azure
Portkey / LiteLLM	Você quer um gateway agnóstico de provedor com um painel	SaaS de terceiros; dados saem de sua nuvem

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills