Exposición de la API REST en API Management como un servidor MCP

APLICA A: desarrollador | Básico | Básico v2 | Estándar | Estándar v2 | Premium | Premium v2

En API Management, puede exponer una API REST administrada en API Management como un servidor remoto del Protocolo de contexto de modelo (MCP) mediante su puerta de enlace de IA integrada. Exponga una o varias de las operaciones de API como herramientas a las que pueden llamar los clientes MCP mediante el protocolo MCP.

Azure API Management también admite la integración segura con servidores compatibles con MCP existentes: servidores de herramientas hospedados fuera de API Management. Para obtener más información, consulte Exposición de un servidor MCP existente.

Más información sobre:

• Compatibilidad con el servidor MCP en API Management
• Funcionalidades de puerta de enlace de IA

Limitaciones

• API Management admite actualmente herramientas de servidor MCP, pero no admite recursos o avisos de MCP.
• API Management no admite actualmente funcionalidades de servidor MCP en áreas de trabajo.

Prerrequisitos

• Si aún no tiene una instancia de API Management, realice el inicio rápido siguiente: Creación de una instancia de Azure API Management. La instancia debe estar en uno de los niveles de servicio que admita servidores MCP.

• Asegúrese de que la instancia administra una API compatible con HTTP (cualquier API importada como API REST, incluidas las API importadas de recursos de Azure) que desea exponer como un servidor MCP. Para importar una API de ejemplo, consulte Importación y publicación de la primera API.

  Nota:

  Otros tipos de API de API Management que no son compatibles con HTTP no se pueden exponer como servidores MCP.

• Si habilita el registro de diagnóstico a través de Application Insights o Azure Monitor en el ámbito global (todas las API) para la instancia del servicio API Management, establezca la opción Número de bytes de carga para registrar la respuesta de front-end en 0. Esta configuración impide el registro no deseado de cuerpos de respuesta en todas las API y ayuda a garantizar el funcionamiento adecuado de los servidores MCP. Para registrar cargas útiles selectivamente para API específicas, configure los ajustes individualmente en el ámbito de la API, lo que permite un control específico sobre el registro de respuestas.

• Para probar el servidor MCP, puede usar Visual Studio Code con acceso a GitHub Copilot o herramientas como MCP Inspector.

Exponer la API como un servidor MCP

Siga estos pasos para exponer una API de REST administrada en API Management como servidor MCP:

1. En Azure Portal, vaya a la instancia de API Management.
2. En el menú de la izquierda, en API, seleccione Servidores MCP>+ Crear servidor MCP.
3. Seleccione Exponer una API como servidor MCP.
4. En servidor MCP back-end:
   1. Seleccione una API administrada para exponerla como un servidor MCP.
   2. Seleccione una o varias operaciones de API para exponerlas como herramientas. Puede seleccionar todas las operaciones o solo operaciones específicas.

      Nota:

      Puede actualizar las operaciones expuestas como herramientas más adelante en la hoja Herramientas del servidor MCP.

5. En nuevo servidor MCP:
   1. Escriba un Nombre para el servidor MCP en API Management.
   2. Opcionalmente, escriba una Descripción para el servidor MCP.
6. Selecciona Crear.

• El servidor MCP se crea y las operaciones de API se exponen como herramientas.
• El servidor MCP aparece en la hoja Servidores MCP. La columna Dirección URL del servidor muestra el punto de conexión del servidor MCP para llamar a pruebas o dentro de una aplicación cliente.

Configurar directivas para el servidor MCP

Configure una o varias directivas de API Management para ayudar a administrar el servidor MCP. Las directivas se aplican a todas las operaciones de API expuestas como herramientas en el servidor MCP. Use estas directivas para controlar el acceso, la autenticación y otros aspectos de las herramientas.

Más información sobre la configuración de directivas:

• Directivas de Azure API Management
• Transformación y protección de la API
• Establecimiento y edición de directivas
• Protección del acceso al servidor MCP

Precaución

No acceda al cuerpo de la respuesta usando la variable context.Response.Body en las políticas del servidor MCP. Al hacerlo, se desencadena el almacenamiento en búfer de respuesta, que interfiere con el comportamiento de streaming requerido por los servidores MCP y puede provocar que no funcionen correctamente.

Para configurar directivas para el servidor MCP, siga estos pasos:

1. En Azure Portal, vaya a la instancia de API Management.

2. En el menú de la izquierda, en API, seleccione Servidores MCP.

3. Seleccione un servidor MCP en la lista.

4. En el menú izquierdo, en MCP, seleccione Directivas.

5. En el editor de directivas, agregue o edite las directivas que desea aplicar a las herramientas del servidor MCP. Defina las directivas en formato XML.

   Por ejemplo, puede agregar una directiva para limitar las llamadas a las herramientas del servidor MCP (en este ejemplo, una llamada por cada 60 segundos por sesión de 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>
   

   

Nota:

API Management evalúa las directivas configuradas en el ámbito global (todas las API) antes de evaluar las directivas en el ámbito del servidor MCP.

Validar y usar el servidor MCP

Use un agente LLM compatible (como GitHub Copilot, Kernel semántico o Copilot Studio) o un cliente de prueba (como curl) para llamar al punto de conexión de MCP hospedado en API Management. Asegúrese de que la solicitud incluye los encabezados o tokens adecuados y confirme el enrutamiento y la respuesta correctos del servidor MCP.

Sugerencia

Si usa el Inspector de MCP para probar un servidor MCP administrado por API Management, use la versión 0.9.0.

Adición del servidor MCP en Visual Studio Code

En Visual Studio Code, use el chat de GitHub Copilot en modo agente para agregar el servidor MCP y usar las herramientas. Para obtener información sobre los servidores MCP en Visual Studio Code, consulte Uso de servidores MCP en VS Code.

Para agregar el servidor MCP en Visual Studio Code:

1. Use el comando MCP: Agregar servidor desde la paleta de comandos.

2. Cuando se le solicite, seleccione el tipo de servidor: HTTP (HTTP o Eventos enviados por el servidor).

3. Escriba la dirección URL del servidor MCP en API Management. Por ejemplo, https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp para el punto de conexión de MCP.

4. Escriba un identificador de servidor de su elección.

5. Seleccione si desea guardar la configuración en la configuración del área de trabajo o en la configuración del usuario.

   • Configuración del área de trabajo : la configuración del servidor se guarda en un .vscode/mcp.json archivo solo disponible en el área de trabajo actual.

   • Configuración del usuario: la configuración del servidor se agrega al archivo global settings.json y está disponible en todas las áreas de trabajo. La configuración es similar a la siguiente:

   

Agregue campos a la configuración JSON para ajustes como el encabezado de autenticación. En el ejemplo siguiente se muestra la configuración de una clave de suscripción de API Management que se pasa en un encabezado como valor de entrada. Más información sobre el formato de configuración

Uso de herramientas en modo de agente

Después de agregar un servidor MCP en Visual Studio Code, puede usar herramientas en modo agente.

1. En el chat de GitHub Copilot, seleccione Modo de agente y seleccione el botón Herramientas para ver las herramientas disponibles.

   

2. Seleccione una o varias herramientas del servidor MCP para que estén disponibles en el chat.

   

3. Escriba un mensaje en el chat para invocar la herramienta. Por ejemplo, si seleccionó una herramienta para obtener información sobre un pedido, puede preguntar al agente sobre un pedido.

   Get information for order 2
   

   Seleccione Continuar para ver los resultados. El agente usa la herramienta para llamar al servidor MCP y devuelve los resultados en el chat.

   

Solución de problemas y problemas conocidos

Problema	Causa	Solución
Error 401 Unauthorized del back-end	Encabezado de autorización no reenviado	Si es necesario, use la directiva set-header para adjuntar manualmente el token
La llamada API funciona en API Management, pero se produce un error en el agente	Dirección URL base incorrecta o token que falta	Comprobar las directivas de seguridad y el punto de conexión
Se produce un error en el streaming del servidor MCP cuando se habilitan los registros de diagnóstico	Registro del cuerpo de respuesta o acceso al cuerpo de respuesta a través de la directiva interfiere con el transporte MCP	Deshabilitación del registro del cuerpo de respuesta en el ámbito Todas las API: consulte Requisitos previos

Contenido relacionado

• Ejemplo: Autorización de servidores MCP con metadatos de recursos protegidos (PRM)

• Ejemplo: Protección de servidores MCP remotos mediante Azure API Management (experimental)

• Laboratorio de autorización de cliente de MCP

• Uso de la extensión de Azure API Management para VS Code para importar y administrar LAS API

• Registro y detección de servidores MCP remotos en el Centro de API de Azure

• Exposición de la API de REST en API Management como un servidor MCP

• Exposición y control del servidor MCP existente