Configuración de la autenticación para herramientas de Protocolo de contexto de modelo (MCP)

La mayoría de los servidores del Protocolo de contexto de modelo (MCP) requieren autenticación para acceder al servidor y a su servicio subyacente. La autenticación adecuada garantiza que los agentes puedan conectarse de forma segura a los servidores MCP, invocar sus herramientas y acceder a los recursos protegidos a la vez que mantienen los controles de acceso adecuados.

En este artículo, usted:

Requisitos previos

Antes de comenzar, necesita lo siguiente:

• Acceso al portal de Foundry y a un proyecto. Si no tiene uno, consulte Creación de proyectos en Foundry.
• Permisos para crear conexiones de proyecto y configurar agentes. Para obtener más información, consulte Control de acceso basado en rol en el portal de Foundry.
• Dirección URL del punto de conexión del servidor MCP remoto al que desea conectarse.
• Credenciales para el método de autenticación seleccionado:
  • Autenticación basada en claves: una clave de API, un token de acceso personal (PAT) u otro token.
  • Microsoft Entra autenticación: asignaciones de roles para la identidad del agente o la identidad administrada del proyecto en el servicio subyacente.
  • Paso directo de identidad de OAuth: configuración de OAuth administrada o registro de aplicación de OAuth (OAuth personalizado).

Elección de un método de autenticación

En general, existen dos escenarios de autenticación:

• Autenticación compartida: cada usuario del agente usa la misma identidad para autenticarse en el servidor MCP. El contexto del usuario no persiste.
• Autenticación individual: cada usuario se autentica con su propia cuenta para que su contexto de usuario persista.

Use las instrucciones siguientes para elegir un método:

Métodos de autenticación admitidos

Autenticación basada en claves

Use la autenticación basada en claves cuando el servidor MCP requiera una clave de API, un token de acceso personal o una credencial similar, y no es necesario conservar el contexto de usuario individual.

Pase una clave de API, un token de acceso personal (PAT) u otras credenciales a los servidores MCP que admitan la autenticación basada en claves. Para mejorar la seguridad, almacene las credenciales compartidas en una conexión de proyecto en lugar de pasarlas en tiempo de ejecución.

Al conectar un servidor MCP a un agente en el portal de Foundry, Foundry crea una conexión de proyecto automáticamente. Proporcione el nombre de credencial y el valor de la credencial. Por ejemplo, si te conectas al servidor MCP de GitHub, puedes proporcionar lo siguiente:

• Nombre de credencial: Authorization
• Valor de credencial: Bearer <your-personal-access-token>

Cuando el agente invoca el servidor MCP, el servicio del agente recupera las credenciales de la conexión del proyecto y las pasa al servidor MCP.

Para seguridad:

• Use las credenciales con privilegios mínimos siempre que sea posible.
• Rotar tokens con regularidad.
• Restrinja el acceso a proyectos que contienen secretos compartidos.

autenticación de Microsoft Entra

Use Microsoft Entra autenticación cuando el servidor MCP (y su servicio subyacente) admita tokens de Microsoft Entra. Este método elimina la necesidad de administrar secretos y proporciona rotación automática de tokens.

Uso de la autenticación de identidad del agente (versión preliminar)

Use la identidad del agente cuando desee que la autenticación tenga como ámbito un agente específico. Este enfoque es ideal cuando tiene varios agentes que necesitan distintos niveles de acceso al mismo servidor MCP.

Use la identidad del agente para autenticarse con servidores MCP que admitan la autenticación de identidad del agente. Si crea el agente mediante el servicio de agente, se le asigna automáticamente una identidad de agente.

Antes de publicar, todos los agentes del proyecto Foundry comparten la misma identidad de agente. Después de publicar un agente, el agente obtiene una identidad de agente única.

Asegúrese de que la identidad del agente tenga las asignaciones de roles necesarias en el servicio subyacente que activa el servidor MCP.

Cuando el agente invoca el servidor MCP, el servicio del agente usa la identidad del agente disponible para solicitar un token de autorización y lo pasa al servidor MCP.

Uso de la autenticación de identidad administrada del proyecto

Use la identidad administrada del proyecto cuando desee que todos los agentes de un proyecto compartan el mismo nivel de acceso o cuando el servidor MCP requiera una identidad administrada en lugar de una identidad del agente.

Use la identidad administrada del proyecto foundry para autenticarse con servidores MCP que admiten la autenticación de identidad administrada.

Asegúrese de que la identidad administrada del proyecto tiene las asignaciones de roles necesarias en el servicio subyacente que impulsa el servidor MCP.

Cuando el agente invoca el servidor MCP, el servicio del agente usa la identidad administrada del proyecto para solicitar un token de autorización y lo pasa al servidor MCP.

Transferencia de identidad de OAuth

El acceso directo de identidad de OAuth está disponible para la autenticación tanto en Microsoft como en servidores MCP que no pertenecen a Microsoft, así como en servicios subyacentes compatibles con OAuth, incluidos Microsoft Entra.

Utiliza el acceso directo de identidad de OAuth para solicitar que los usuarios que interactúan con tu agente inicien sesión en el servidor MCP y su servicio subyacente. El servicio de agente almacena de forma segura las credenciales del usuario y las usa solo en el contexto del agente que se comunica con el servidor MCP.

Cuando se usa el paso de identidad de OAuth, el servicio de agente genera un enlace de consentimiento la primera vez que un usuario determinado necesita autorizar el acceso. Una vez que el usuario inicia sesión y da su consentimiento, el agente puede detectar e invocar herramientas en el servidor MCP con las credenciales de ese usuario.

El servicio de agente admite dos opciones de OAuth: OAuth administrada y OAuth personalizada.

• Con OAuth administrado, Microsoft o el publicador del servidor MCP administra la aplicación OAuth.
• Con OAuth personalizado, aportas tu propio registro de aplicación de OAuth.

Al configurar OAuth personalizado, proporcione la siguiente información:

• Id. de cliente: obligatorio
• Secreto de cliente: opcional (depende de la aplicación de OAuth)
• Dirección URL de autenticación: obligatorio
• Url de actualización: necesaria (si no tiene una dirección URL de actualización independiente, puede usar la dirección URL del token en su lugar).
• Dirección URL del token: obligatorio
• Ámbitos: opcional

Flujo mediante la transferencia directa de identidad de OAuth

El ámbito de OAuth es por nombre de herramienta (conexión) por proyecto Foundry. Se pide a cada nuevo usuario que use una nueva herramienta (conexión) en un proyecto foundry para proporcionar consentimiento.

• Cuando un usuario intenta usar por primera vez una nueva herramienta en un proyecto Foundry, la salida de respuesta comparte el vínculo de consentimiento en response.output_item. Puede encontrar el vínculo de consentimiento en el tipo de elemento oauth_consent_request, en consent_link. Muestra este enlace de consentimiento al usuario.

  "type":"response.output_item.done",
  "sequence_number":7,
  "output_index":1,
  "item":{
      "type":"oauth_consent_request",
      "id":"oauthreq_10b0f026610e2b76006981547b53d48190840179e52f39a0aa",
      "created_by":{},
      "consent_link":"https://logic-swedencentral-001.consent.azure-apihub.net/login?data=xxxx"
  }
  

  Vea un ejemplo:

• Se pide al usuario que inicie sesión y dé su consentimiento después de revisar el acceso necesario. Después de dar el consentimiento correctamente, el usuario ve un cuadro de diálogo como este ejemplo:

• Una vez que el usuario haya cerrado el cuadro de diálogo, debe enviar otra respuesta con el identificador de respuesta anterior.

  # Requires: azure-ai-projects >= 2.0.0
  from azure.ai.projects import AIProjectClient
  from azure.identity import DefaultAzureCredential
  
  # Submit another response after user consent
  response = client.responses.create(
       previous_response_id="YOUR_PREVIOUS_RESPONSE_ID",
       input=user_input,
       extra_body={
           "agent_reference": {"name": agent.name, "type": "agent_reference"},
           "tool_choice": "required",
           "stream": True
       },
  )
  

Una vez que el usuario haya iniciado sesión y dado su consentimiento una vez, no es necesario dar su consentimiento en el futuro.

Lleve su propio registro de aplicación de Microsoft Entra

Para usar el acceso directo de identidad con servicios Microsoft, traiga su propio registro de aplicaciones Microsoft Entra. Al traer su propio registro de aplicaciones Microsoft Entra, controla qué permisos concede.

En los pasos siguientes se usa el servidor MCP del Agente 365 como ejemplo:

1. Siga la guía de registro app para crear una aplicación de Microsoft Entra y obtener el identificador de cliente y el secreto de cliente.

2. Otorgue permisos con ámbito definido a la aplicación de Microsoft Entra.

   Para los servidores MCP del Agente 365, vaya a Administrar>permisos de API y busque Herramientas del Agente 365. Si no lo encuentra, busque ea9ffc3e-8a23-4a7d-836d-234d7c7565c1. Asigne los permisos que necesita y conceda el consentimiento del administrador para el inquilino.

   Estos son los permisos para cada servidor MCP:

   • Microsoft Outlook servidor MCP de correo (Frontier): McpServers.Mail.All
   • servidor MCP de calendario de Microsoft Outlook (Frontier): McpServers.Calendar.All
   • Microsoft Teams MCP (Frontier) servidor: McpServers.Teams.All
   • Microsoft 365 servidor MCP de perfil de usuario (Frontier): McpServers.Me.All
   • Microsoft SharePoint y OneDrive servidor MCP (Frontier): McpServers.OneDriveSharepoint.All
   • Microsoft SharePoint enumera el servidor MCP (Frontier): McpServers.SharepointLists.All
   • Microsoft Word servidor MCP (Frontier): McpServers.Word.All
   • Microsoft 365 Copilot (Búsqueda) Servidor MCP (Frontier): McpServers.CopilotMCP.All
   • Servidor MCP del Centro de administración de Microsoft 365 (Frontier): McpServers.M365Admin.All
   • Microsoft Dataverse Servidor MCP (Frontier): McpServers.Dataverse.All

3. Vuelva al portal de Foundry y configure el servidor MCP. Conecte una herramienta, vaya a Personalizado y seleccione MCP. Proporcione un nombre y un punto de conexión de servidor MCP y, a continuación, seleccione Paso de identidad de OAuth:

   • id. de cliente y secreto de cliente
   • dirección URL del token: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
   • dirección URL de autenticación: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/authorize
   • dirección URL de recarga: https://login.microsoftonline.com/{tenantId}/oauth2/v2.0/token
   • ámbitos: ea9ffc3e-8a23-4a7d-836d-234d7c7565c1/{permission above}

4. Después de completar la configuración, recibirá una URL de redirección. Agréguelo a la aplicación de Microsoft Entra.

Acceso no autenticado

Use acceso no autenticado solo cuando el servidor MCP no requiera autenticación. Este método es adecuado para los servidores MCP públicos que proporcionan acceso abierto a sus herramientas o para servidores MCP privados dentro de la red virtual que dependen del aislamiento de nivel de red en lugar de la autenticación explícita.

Configuración de la autenticación para un servidor MCP

1. Identifique el servidor MCP remoto al que desea conectarse.

2. Cree o seleccione una conexión de proyecto que almacene el punto de conexión del servidor MCP, el tipo de autenticación y las credenciales necesarias.

   Si conecta el servidor MCP en el portal de Foundry, el portal crea automáticamente la conexión del proyecto.

3. Cree o actualice un agente con una mcp herramienta con la siguiente información:

   1. server_url: la dirección URL del servidor MCP. Por ejemplo, https://api.githubcopilot.com/mcp/.
   2. server_label: identificador único de este servidor MCP para el agente. Por ejemplo, github.
   3. require_approval: opcionalmente, determine si se requiere aprobación. Los valores admitidos son:
      • always: un desarrollador debe proporcionar aprobación para cada llamada. Si no proporciona un valor, este valor es el valor predeterminado.
      • never: no se requiere ninguna aprobación.
      • {"never":[<tool_name_1>, <tool_name_2>]}: proporciona una lista de herramientas que no requieren aprobación.
      • {"always":[<tool_name_1>, <tool_name_2>]}: proporciona una lista de herramientas que requieren aprobación.
   4. project_connection_id: el nombre de conexión que almacena el punto de conexión del servidor MCP, la selección de autenticación y la información pertinente. Si proporciona diferentes puntos de conexión en comparación con server_url, se usará el punto de conexión en la conexión.

4. Ejecute el agente.

5. Si el modelo intenta invocar una herramienta en el servidor MCP con la aprobación necesaria o el usuario debe iniciar sesión para el paso de identidad de OAuth, revise la salida de la respuesta:

   • Vínculo de consentimiento: oauth_consent_request
   • Solicitud de aprobación: mcp_approval_request

   Después de que el usuario inicie sesión o apruebe la llamada, envíe otra respuesta para continuar.

Validar

Después de configurar la autenticación, compruebe que la conexión funciona correctamente:

1. Inicie una llamada de herramienta MCP desde el agente enviando un mensaje que haga que el agente utilice una de las herramientas del servidor MCP.
2. Confirme que la llamada a la herramienta se completa correctamente. Debería ver la salida de la herramienta en la respuesta del agente sin errores de autenticación.
3. Si usa el paso de identidad de OAuth:
   • Confirme que un nuevo usuario recibe un vínculo de consentimiento (oauth_consent_request en la respuesta).
   • Después de que el usuario dé su consentimiento, confirme que las llamadas posteriores a la herramienta se realizan correctamente sin volver a pedir su consentimiento.
   • Pruebe con un usuario diferente para comprobar que el flujo de consentimiento por usuario funciona correctamente.

Solución de problemas

Hospedaje de un servidor MCP local

Si ha desarrollado un servidor MCP personalizado o desea usar un servidor MCP de código abierto que se ejecuta localmente, debe hospedarlo en la nube antes de conectarlo al servicio del agente.

El entorno de ejecución del servicio del agente solo acepta un punto de conexión remoto del servidor MCP. Si desea agregar herramientas desde un servidor MCP local, debe hospedarla automáticamente en Azure Container Apps o Azure Functions para obtener un punto de conexión de servidor MCP remoto.

El punto de conexión remoto puede ser un punto de conexión público o un punto de conexión privado dentro de la red virtual. En el caso de los servidores MCP privados, implemente la aplicación contenedora con entrada solo interna en una subred MCP dedicada delegada en Microsoft.App/environments. Para empezar, use la plantilla 19-hybrid-private-resources-agent-setup . Para más información sobre la compatibilidad de herramientas en entornos aislados de red, consulte Herramientas del agente con aislamiento de red.

Tenga en cuenta los siguientes puntos al intentar hospedar servidores MCP locales en la nube:

Pasos siguientes

• Conectar a servidores del Protocolo de Contexto de Modelo
• Configuración de redes privadas para foundry Agent Service
• Conceptos de identidad del agente en Foundry
• Control de acceso basado en rol en el portal de Foundry
• Adición de una conexión en Foundry