Compilación y registro de un servidor de Protocolo de contexto de modelo (MCP)

El Protocolo de contexto de modelo (MCP) proporciona una interfaz estándar para que los agentes de IA interactúen con las API y los servicios externos. Cuando necesite integrar sistemas empresariales privados o internos que no tengan implementaciones de servidor MCP existentes, puede crear su propio servidor personalizado. En este artículo se muestra cómo crear un servidor MCP remoto mediante Azure Functions, registrarlo en un catálogo de herramientas de una organización privada mediante Azure Centro de API y conectarlo al servicio Foundry Agent Service.

Este enfoque le permite integrar de forma segura las API internas y los servicios en el ecosistema de Microsoft Foundry, lo que permite a los agentes llamar a las herramientas específicas de la empresa a través de una interfaz MCP estandarizada.

Requisitos previos

• Un proyecto Foundry con el Servicio de Agente habilitado. Para obtener instrucciones de configuración, consulte Inicio rápido: Creación de un agente de solicitud.
• Una suscripción de Azure y permisos para crear recursos. Como mínimo, normalmente necesita el rol Colaborador en el grupo de recursos de destino.
• Python versión 3.11 o posterior instalada en el equipo de desarrollo local.
• Azure Functions Core Tools versión 4.0.7030 o posterior.
• Azure CLI para desarrolladores instalada para la automatización de la implementación.
• Para el desarrollo y depuración local:
  • Visual Studio Code
  • Azure Functions extensión para Visual Studio Code
• Un recurso Azure API Center (opcional, necesario solo para el registro del catálogo de herramientas de la organización).

Descripción del flujo de solicitudes

Los servidores MCP remotos pueden ser personalizados (como se describe en este artículo) u ofertas proporcionadas por Microsoft disponibles en el catálogo Foundry Add Tools, como Azure DevOps MCP Server (preview). La experiencia de conexión y gobernanza en Foundry es similar para ambos, con diferencias en la autenticación y el ámbito específicos del proveedor.

El flujo de alto nivel tiene este aspecto:

1. Puede implementar un servidor MCP (en este artículo se usa Azure Functions) que expone una o varias herramientas de MCP.
2. Opcionalmente, puede registrar el servidor en Azure CENTRO de API para que aparezca en un catálogo de herramientas de la organización.
3. En el portal de Foundry, conectas el servidor MCP al servicio Agente.
4. Cuando un agente necesita una herramienta, el servicio del agente llama al punto de conexión del servidor MCP.
5. El servidor MCP valida la solicitud, llama a la API interna y devuelve el resultado de la herramienta.

Creación de un servidor MCP mediante Azure Functions

Azure Functions es un servicio de proceso sin servidor que proporciona funcionalidad de escala a cero, escalado de ráfagas y características empresariales, incluido el acceso basado en identidad y las redes virtuales. El modelo de programación ligera facilita la compilación de servidores MCP para que pueda centrarse en implementar la lógica de negocios en lugar de en la administración de infraestructuras.

1. Abra un terminal o una consola de comandos y diríjase a la carpeta donde desea crear el proyecto.

2. Ejecute el comando azd init para inicializar el proyecto desde este plantilla de servidor MCP de ejemplo:

   azd init --template remote-mcp-functions-python -e mcpserver-python
   

3. Revise la estructura de código de ejemplo. La plantilla incluye:

   • Definiciones de función para puntos de conexión de MCP.
   • Configuración para la autenticación y autorización.
   • Scripts de implementación para Azure.

4. Personalice las funciones del servidor MCP para exponer las API y los servicios específicos. Modifique el código de función para implementar las herramientas y funcionalidades que necesitan los agentes.

5. Pruebe el servidor MCP localmente mediante Azure Functions Core Tools:

   func start
   

6. Implemente el servidor MCP en Azure mediante la CLI para desarrolladores de Azure:

   azd up
   

   Siga las indicaciones para seleccionar la suscripción Azure y el grupo de recursos.

7. Una vez completada la implementación, guarde la siguiente información para los pasos posteriores:

   • Punto de conexión del servidor MCP remoto: https://{function_app_name}.azurewebsites.net/runtime/webhooks/mcp
   • Información de autenticación: para la autenticación de clave de acceso, tenga en cuenta la clave del sistema mcp_extension en el portal de Azure.

   Si prefiere un flujo de trabajo de interfaz de línea de comandos (CLI) para recuperar claves de acceso de funciones, consulte Trabajar con claves de acceso en Azure Functions.

8. (Opcional) Para usar Microsoft Entra autenticación en lugar del acceso basado en claves, habilite la autenticación Azure Functions en la aplicación de funciones, establezca la audiencia permitida en el URI de identificador de aplicación esperado por el punto de conexión de MCP y compruebe la ruta de acceso del webhook de MCP (/runtime/webhooks/mcp). Para obtener pasos detallados de configuración, consulte el tutorial Host un servidor MCP en Azure Functions.

Para obtener más detalles de implementación, incluidos patrones de autenticación avanzados y solución de problemas, consulte el tutorial Host un servidor MCP en Azure Functions.

Protección del punto de conexión del servidor MCP

Antes de compartir el servidor MCP con otros usuarios, defina y aplique una línea base de seguridad:

• Requerir autenticación. Evite el acceso anónimo a menos que el escenario lo necesite explícitamente.
• Trate las credenciales como secretos. No codifique las claves de código duro en el código ni compruébalas en el control de código fuente. Almacene secretos en un almacén seguro, como Azure Key Vault.
• Implemente privilegios mínimos para las llamadas de bajada. Si el servidor MCP llama a las API internas, establezca los permisos de ámbito solo en lo que necesitan las herramientas expuestas.
• Registra y supervisa las llamadas a herramientas. Utiliza el registro de Azure Functions para realizar un seguimiento de las solicitudes y solucionar errores.

Al usar Azure Functions para hospedar el servidor MCP, las opciones de autenticación se asignan a Foundry de la siguiente manera:

• Claves de función (x-functions-key): corresponde a la autenticación basada en claves en Foundry.
• Microsoft Entra: corresponde a la autenticación de Microsoft Entra en Foundry (identidad del agente o identidad administrada del proyecto).
• Passthrough de identidad OAuth: Corresponde al Passthrough de identidad OAuth (OBO) en Foundry.
• Sin autenticar: se admite en escenarios limitados, pero no se recomienda para cargas de trabajo de producción.

Para los patrones de autenticación del servicio de agente (por ejemplo, autenticación basada en claves, identidades de Microsoft Entra y paso directo de identidad de OAuth), consulte MCP server authentication.

Para obtener instrucciones operativas y de gobernanza al ejecutar herramientas de MCP, consulte Procedimientos recomendados e instrucciones de seguridad de Foundry MCP Server.

Registro del servidor MCP en el catálogo de herramientas de la organización

Al registrar el servidor MCP en Azure API Center, se crea un catálogo de herramientas de la organización privada. Este paso es opcional, pero se recomienda para compartir servidores MCP en toda la organización con gobernanza y detectabilidad coherentes.

Para registrar el servidor MCP:

1. Inicie sesión en el portal Azure y vaya al recurso del Centro de API de Azure.

   Propina

   El nombre del Centro de APIs se convierte en el nombre del catálogo de herramientas privado en el filtro del registro. Elija un nombre informativo que ayude a los usuarios a identificar el catálogo de herramientas de su organización.

2. En el panel de navegación izquierdo, despliegue Inventario y seleccione Activos.

3. Seleccione Registrar un recurso y elija Servidor MCP.

4. Proporcione la información necesaria sobre el servidor MCP.

5. Configure entornos e implementaciones siguiendo el tutorial: Añadir entornos e implementaciones para APIs en Azure API Center.

6. Configure la autenticación para el servidor MCP (opcional):

   En el panel de navegación izquierdo del recurso del Centro de API, seleccione Gobernanza>Autorización.

   

7. Seleccione Agregar configuración.

8. Elija el esquema de seguridad que coincida con los requisitos del servidor MCP:

   • Clave de API: los desarrolladores proporcionan la clave de API durante la configuración de la herramienta en Foundry
   • OAuth: Configuración de parámetros de autenticación de OAuth 2.0
   • HTTP: Configuración de la autorización del token de portador

9. Proporcione los detalles de autenticación necesarios para el esquema seleccionado.

   Nota

   Si elige autenticación de clave de API, la clave que almacena en Azure Key Vault no se usa automáticamente en Foundry. Los desarrolladores deben proporcionar la clave de API al configurar la conexión del servidor MCP.

10. Configurar la administración de acceso (opcional):

    a. Vaya al servidor MCP registrado en el Centro de API.

    b. Seleccione Detalles>Versiones>Administra acceso (versión preliminar).

    c. Configure qué usuarios o grupos pueden acceder a este servidor MCP a través del catálogo organizativo.

Después del registro, el servidor MCP aparece en el catálogo de herramientas de Foundry con la configuración de gobernanza y autenticación que configuró.

Uso compartido de servidores MCP más allá de la organización

El catálogo de herramientas organizacionales (Azure API Center) está adaptado al ámbito de tu organización. Para compartir servidores MCP con equipos externos o con la comunidad más amplia, considere la posibilidad de distribuirlos a través de un repositorio de GitHub público o privado con instrucciones de configuración. Actualmente no hay ningún marketplace de servidor MCP entre organizaciones, pero el ecosistema de MCP está evolucionando. Compruebe el sitio de especificación de MCP para obtener actualizaciones sobre el descubrimiento y distribución de servidores.

Conexión del servidor MCP al servicio del agente

Puede conectar su servidor MCP al Servicio de Agentes a través del catálogo de herramientas organizacional (si lo ha registrado) o como una herramienta MCP personalizada.

Conexión mediante el catálogo de herramientas de la organización

Si registró el servidor MCP en Azure CENTRO de API, los usuarios con acceso adecuado pueden detectarlo y configurarlo:

1. En el portal de Foundry, vaya a tu proyecto.

2. Vaya a Herramientas de compilación> o abra Agent Builder.

3. Examine el catálogo de herramientas de la organización para buscar el servidor MCP registrado.

4. Siga las instrucciones de configuración que se muestran en el catálogo de herramientas para agregar el servidor al agente.

El mismo servidor MCP se puede reutilizar mediante varios clientes (como Foundry Agent Service y herramientas de desarrollo como Visual Studio Code), siempre que la autenticación esté configurada adecuadamente.

Conexión mediante una herramienta de MCP personalizada

Si no registra el servidor MCP en el catálogo organizativo, agréguelo directamente como una herramienta personalizada:

1. En el portal de Foundry, vaya a tu proyecto.

2. Vaya a Herramientas de compilación> o abra Agent Builder.

3. Seleccione Agregar herramienta>Custom>Model Context Protocol.

4. Escriba los detalles del servidor MCP:

   • Nombre: nombre único para el servidor MCP remoto
   • Punto de conexión del servidor MCP remoto: escriba la dirección URL del punto de conexión del servidor MCP remoto (por ejemplo, https://{function_app_name}.azurewebsites.net/runtime/webhooks/mcp)
   • Autenticación: seleccione el método de autenticación:
     • Basado en claves: proporcione la credencial como "x-functions-key": "{mcp_extension_system_key}".
     • Microsoft Entra ID: seleccione identidad del agente o identidad administrada del proyecto. Proporcione la Audiencia (URI de ID de aplicación) configurada en el servidor MCP. Asegúrese de que la identidad seleccionada tiene los permisos necesarios en function App.
     • Transferencia de identidad de OAuth (OBO): Proporcione el ID de cliente, el secreto del cliente, la URL de autorización, la URL del token, (si procede) la URL de actualización y los ámbitos del proveedor de OAuth. Use esta opción cuando necesite actuar en nombre del usuario que ha iniciado sesión.

5. Seleccione Conectar para registrar la herramienta DE MCP personalizada.

Para conocer los pasos de configuración detallados (incluidas las conexiones de proyecto y los flujos de trabajo de aprobación), consulte Conexión a servidores de Protocolo de contexto de modelo (versión preliminar).

Después de conectar tu servidor MCP, los agentes en tu proyecto Foundry pueden llamar a las herramientas y funciones expuestas por tu servidor personalizado. El mismo servidor MCP se puede reutilizar mediante varios clientes (como Foundry Agent Service y herramientas de desarrollo como Visual Studio Code), siempre que la autenticación esté configurada adecuadamente.

Comprobar que el servidor MCP funciona de un extremo a otro

Después de implementar y conectar el servidor, compruebe que el servidor se puede detectar y que un agente puede invocar correctamente una herramienta.

1. En el portal de Foundry, confirme que el servidor MCP aparece en la lista de herramientas del proyecto.

2. Cree un agente (o abra un agente existente) y agregue la herramienta de servidor MCP.

3. Ejecute un mensaje que necesite una de sus herramientas MCP.

4. Si la aprobación está habilitada, revise el nombre de la herramienta y los argumentos y, a continuación, apruebe la llamada.

5. Confirme que la llamada a la herramienta funciona correctamente.

   Si se produce un error en la llamada a la herramienta, abra los registros de Function App en Azure portal para confirmar que se invocó el punto de conexión de MCP y para diagnosticar errores.

Solución de problemas

Estos son algunos problemas comunes que podría surgir al compilar y conectar el servidor MCP:

• Error en la conexión del servidor MCP: confirme que la dirección URL del servidor es accesible desde el servicio del agente y usa la ruta de acceso del webhook de MCP (/runtime/webhooks/mcp). En el caso de los puntos de conexión públicos, compruebe que la dirección URL es accesible públicamente. En el caso de los puntos de conexión privados, compruebe que el programa de instalación del agente estándar con redes privadas está configurado correctamente. Compruebe los registros de Function App en Azure portal para ver si hay errores.
• Errores de autenticación (401/403): compruebe que usa la clave o el token correctos para el método de autenticación seleccionado. Gire las claves que podrían haberse expuesto y actualice las credenciales guardadas.
• Microsoft Entra errores de autenticación (401/403): Compruebe que la audiencia (URI de ID de aplicación) en la configuración de la herramienta de Foundry coincide con la audiencia permitida configurada en la configuración de autenticación de Function App. Confirme que la identidad seleccionada (identidad del agente o identidad administrada del proyecto) tiene las asignaciones de roles necesarias en function App. Compruebe que la dirección URL del emisor es correcta para el inquilino de Microsoft Entra.
• Errores de transferencia de identidad de OAuth: compruebe que la dirección URL de autorización, la dirección URL del token y los ámbitos de la configuración de la herramienta Foundry coinciden con la configuración del proveedor de OAuth. Confirme que el identificador de cliente y el secreto de cliente son correctos y no han expirado. Los desajustes de ámbito o las direcciones URL de punto de conexión incorrectas son causas comunes de fallos en el intercambio de tokens de OBO.
• Problemas de descubrimiento de herramientas: si registró el servidor en Azure Centro de API, confirme que la API está publicada y tiene acceso a ella. Si ha agregado una herramienta personalizada, confirme que la dirección URL del punto de conexión es correcta.
• La llamada a la herramienta se realiza correctamente, pero se produce un error en una API interna: revise los registros del servidor MCP para confirmar qué solicitud se envió a la API de bajada. Compruebe que la identidad del servidor MCP o las credenciales de API tienen los permisos necesarios.

Limpieza de recursos

Cuando haya terminado, elimine los recursos de Azure creados mediante la plantilla para evitar cargos recurrentes.

1. En la carpeta del proyecto del servidor MCP, ejecute:

   azd down --purge
   

2. Si registró el servidor en el Centro de API de Azure, elimine la entrada de API si ya no la necesita.

Contenido relacionado

• Autenticación del servidor MCP
• Introducción a Foundry MCP Server (versión preliminar) mediante Visual Studio Code
• Procedimientos recomendados y instrucciones de seguridad del servidor MCP de Foundry
• Explore las herramientas disponibles y los mensajes de ejemplo para Foundry MCP Server (versión preliminar)
• Agregar entornos e implementaciones en Azure API Center
• guía para desarrolladores Azure Functions Python