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

Por qué usarlo

Características clave

APIM frente a servidores Azure OpenAI / MCP como capa de gobernanza
Cuotas de tokens por suscripción, por modelo, por equipo
Caché de completados deterministas para reducir gastos
Equilibrio de carga + conmutación por error en múltiples regiones AOAI
Registro completo de solicitudes/respuestas en App Insights para auditoría

Demo en vivo

Cómo se ve en la práctica

azure-ai-gateway.replay ▶ listo

0/0

Instalar

Elige tu 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"
      ]
    }
  }
}

Abre Claude Desktop → Settings → Developer → Edit Config. Reinicia después de guardar.

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

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

Cursor usa el mismo esquema mcpServers que Claude Desktop. La configuración del proyecto prevalece sobre la global.

VS Code → Cline → MCP Servers → Edit

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

Haz clic en el icono MCP Servers de la barra lateral de Cline y luego en "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Mismo formato que Claude Desktop. Reinicia Windsurf para aplicar.

~/.continue/config.json

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

Continue usa un array de objetos de servidor en lugar de un mapa.

~/.config/zed/settings.json

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

Añádelo a context_servers. Zed recarga en caliente al guardar.

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

Un solo comando. Verifica con claude mcp list. Quita con claude mcp remove.

Casos de uso

Usos del mundo real: Azure AI Gateway

Aplicar cuotas de tokens por equipo en despliegues de Azure OpenAI

👤 Equipos de plataforma central que gobiernan el gasto en LLM ⏱ ~30 min advanced

Cuándo usarlo: Múltiples equipos de producto comparten AOAI; el bucle desbocado de un equipo no debería quemar el presupuesto TPM compartido.

Requisitos previos

Instancia de APIM con los patrones de IA-Gateway aplicados — Despliega la arquitectura de referencia desde el repositorio Azure-Samples/AI-Gateway
Clave de suscripción de APIM por equipo — Cada equipo obtiene una suscripción de APIM distinta (clave) que incluye en el encabezado Ocp-Apim-Subscription-Key

Flujo

Revisar cuotas actuales

Enumera suscripciones de APIM con sus cuotas TPM y RPM actuales para el producto AOAI.✓ Copiado

→ Tabla de cuotas por equipo
Reducir un equipo ruidoso

El equipo 'growth' está al 90% de quema TPM diaria. Reduce su cuota de 200k → 100k TPM. Mantén los otros sin cambios.✓ Copiado

→ Cuota actualizada; confirmación
Monitorear después del cambio

Durante la próxima hora, extrae conteos 429 (limitado por velocidad) por suscripción. Confirma que growth está siendo moldeado pero los equipos críticos de prod no se ven afectados.✓ Copiado

→ Aplicación visible en métricas

Resultado: Gasto compartido de AOAI controlado sin eliminar tráfico legítimo de alta prioridad.

Errores comunes

Establecer cuotas demasiado bajas priva de recursos a cargas de trabajo legítimas — Implementa primero en modo sombra (solo registro), luego aplica una vez que entiendas los patrones reales

Configurar conmutación por error de múltiples regiones para un despliegue de Azure OpenAI

👤 SREs que ejecutan cargas de trabajo de IA en producción ⏱ ~45 min advanced

Cuándo usarlo: Una interrupción regional de AOAI (infrecuente pero real) debería conmutar por error de forma transparente a otra región.

Requisitos previos

Despliegues de AOAI en ≥2 regiones (p.ej. Este de EE.UU., Europa Occidental) — Aprovisiona a través de Azure Portal; coincide modelo + versión

Flujo

Inspecciona el grupo de backend actual

Muestra el grupo de backend de APIM para nuestra API AOAI. ¿Cuántos backends, prioridad, configuración de protección de circuitos?✓ Copiado

→ Configuración actual del grupo
Agregar una región secundaria

Agrega el endpoint de AOAI de Europa Occidental como priority=2 con protección de circuitos: 5 fallos en 1 min → abierto durante 5 min. Mantén Este de EE.UU. como principal.✓ Copiado

→ Grupo actualizado, 2 backends configurados
Prueba la conmutación por error

Simula interrupción primaria deshabilitando el backend de Este de EE.UU. durante 2 min. Confirma que el tráfico cambia a Europa Occidental, luego revierte.✓ Copiado

→ Cambio de tráfico observado; reversión verificada

Resultado: Conmutación por error transparente con evidencia de que funciona antes de necesitarla.

Errores comunes

Diferentes regiones tienen diferentes versiones de modelo desplegadas — Fija una versión de modelo que exista en ambas regiones; versiones no coincidentes devuelven silenciosamente diferente calidad

Desplegar caché semántico para reducir costos de prompts repetidos

👤 Equipos de plataforma conscientes de costos ⏱ ~30 min advanced

Cuándo usarlo: Tus usuarios hacen preguntas similares una y otra vez; 30–60% de las llamadas son efectivamente aciertos de caché.

Flujo

Activar política de caché semántico

Habilita la política de búsqueda de caché semántico de APIM en la API de completados de AOAI con umbral de similitud 0.95, TTL 1h.✓ Copiado

→ Política aplicada
Observar tasa de aciertos

Después de 24h, extrae la tasa de aciertos de caché y ahorro de tokens de App Insights.✓ Copiado

→ Tasa de aciertos % + tokens ahorrados
Ajustar umbral

Si la tasa de aciertos <20%, baja el umbral a 0.92 y observa de nuevo. Si hay quejas de calidad, sube nuevamente a 0.97.✓ Copiado

→ Ajuste iterativo con mediciones

Resultado: Ahorro de costos medido en consultas repetidas sin degradar la calidad de salida.

Errores comunes

El caché demasiado agresivo sirve respuestas incorrectas para preguntas similares pero diferentes — Comienza alto (0.97) y solo baja basado en la calidad observada

Combinaciones

Combínalo con otros MCPs para multiplicar por 10

azure-ai-gateway + sentry

Correlaciona picos APIM 5xx con errores del lado de la aplicación

Si Sentry muestra pico 5xx en app X a las 10:02, extrae métricas de APIM para la misma ventana e identifica si la puerta de enlace la causó.✓ Copiado

azure-ai-gateway + notion

Informe semanal de gobernanza de tráfico de IA a Notion

Compila el uso de TPM por equipo para la semana, conteos 429, tasa de aciertos de caché; publica como página de Notion.✓ Copiado

Herramientas

Lo que expone este MCP

Herramienta	Entradas	Cuándo llamar	Coste
list_subscriptions	product_id?	Inventariar equipos consumiendo la puerta de enlace	free (ARM API call)
update_quota	subscription_id, tpm?, rpm?	Ajustar los límites de tokens/solicitudes de un equipo	free
get_backend_pool	api_id	Inspecciona configuración de enrutamiento y conmutación por error	free
update_backend_pool	api_id, backends, policies	Cambiar prioridades, protecciones de circuitos, equilibrio de carga	free
apply_policy	api_id, policy_xml	Desplegar política de APIM (caché, autenticación, registro)	free
get_metrics	api_id, since, until	Observa la forma del tráfico por API	free

Coste y límites

Lo que cuesta ejecutarlo

Cuota de API: Límites de velocidad de Azure Resource Manager (generosos por inquilino)
Tokens por llamada: Lecturas de Política/grupo-backend: 500–2000 tokens
Monetario: El precio de APIM comienza en ~$40/mes (nivel básico); se recomienda nivel estándar para prod
Consejo: El caché semántico generalmente compensa el costo de APIM muchas veces si tu tráfico se repite. Mide la tasa de aciertos para justificar.

Seguridad

Permisos, secretos, alcance

Ámbitos mínimos: Colaborador de APIM en la instancia de APIM de destino

Almacenamiento de credenciales: Credenciales de entidad de servicio de Azure (id cliente/secreto/inquilino) en env

Salida de datos: Llamadas de API ARM a management.azure.com; los cuerpos de prompt/respuesta recorren el propio APIM

No conceder nunca: Propietario en la suscripción Administrador global

El repositorio AI-Gateway es código de referencia/muestra; revisa antes de desplegar literalmente en producción.
El registro de solicitudes/respuestas puede capturar DPI — enmascara en política antes de enviar a App Insights.

Resolución de problemas

Errores comunes y soluciones

401 en llamadas de API ARM

La entidad de servicio carece del rol de Colaborador de APIM en el grupo de recursos. Otorga a través del portal o az cli.

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

La aplicación de política falla — error de validación XML

La política XML de APIM es estricta; usa el editor de políticas del portal para validar, luego copia y pega.

Los 429 persisten después de aumentar la cuota TPM

El despliegue de AOAI subyacente en sí puede ser el cuello de botella. Verifica TPM de despliegue, no solo APIM suscripción TPM.

La tasa de aciertos del caché semántico es 0%

Backend de incrustación para búsqueda de caché no configurado; verifica la referencia de incrustaciones de la política de caché.

Alternativas

Azure AI Gateway vs otros

Alternativa	Cuándo usarla	Contrapartida
Cloudflare AI Gateway	Estás en Cloudflare y quieres enrutamiento LLM multi-proveedor listo para usar	Integración menos profunda con modelos alojados en Azure
Portkey / LiteLLM	Quieres una puerta de enlace agnóstica de proveedor con un panel	SaaS de terceros; los datos salen de tu nube

Más

Recursos

📖 Lee el README oficial en GitHub

🐙 Ver issues abiertas

🔍 Ver todos los 400+ servidores MCP y Skills