Conexión de agentes a herramientas de terceros con servicios MCP

Un servicio MCP es un catálogo de Unity protegible que registra un servidor MCP externo y rige cómo lo usan los agentes. Se hace referencia a él por su nombre de tres niveles, catalog.schema.mcp_service, y se invoca a través de Unity AI Gateway, la capa de control para gestionar el tráfico de IA.

Registrar un servidor MCP como objeto protegible de Unity Catalog significa que lo gestionas con los mismos mecanismos que protegen el resto de activos de Unity Catalog. Entre ellas se incluyen concesiones para controlar quién puede invocarla, la selección de herramientas para limitar las herramientas que expone, las directivas de servicio para permitir o denegar llamadas a herramientas individuales y el registro de auditoría y uso para realizar un seguimiento de cada invocación.

Hay dos maneras de usar los servicios MCP:

Requisitos

• Un área de trabajo habilitada para el catálogo de Unity.

• Un área de trabajo en una región en la que se admite Model Serving. Consulte la disponibilidad de características de servicio de modelos.

Cómo funciona

Un agente llama a un servicio MCP por su dirección URL de unity AI Gateway y cada llamada fluye a través de la misma ruta de acceso regulada:

1. Invoke: el agente envía una solicitud MCP a la dirección URL de unity AI Gateway del servicio, autenticada con la identidad Azure Databricks del autor de la llamada.
2. Autorizar y gestionar: la puerta de enlace comprueba que quien realiza la llamada tiene EXECUTE en el servicio MCP de Unity Catalog. El servicio expone solo las herramientas que seleccionó y evalúa cualquier directiva de servicio adjunta, que puede permitir, denegar o requerir aprobación para la llamada.
3. Proxy con credenciales administradas: la solicitud se reenvía al servidor MCP externo a través de la conexión HTTP del servicio. Azure Databricks almacena las credenciales y controla los flujos de OAuth y la actualización de tokens, por lo que el agente nunca los ve.
4. Registro de uso, auditoría y seguimientos: cada invocación se registra en las tablas del sistema, por lo que puede supervisar la actividad de uso y auditoría a lo largo del tiempo.

Servicios MCP proporcionados por Databricks

Azure Databricks proporciona servicios MCP listos para usar en el system.ai esquema para aplicaciones SaaS comunes, por lo que los agentes pueden llegar a estas herramientas sin hospedar ni registrar su propio servidor MCP. Cada uno es un servicio MCP integrado que se identifica por su nombre en Unity Catalog. Para dar acceso a un agente, concede EXECUTE al servicio (por ejemplo, system.ai.github). No se necesita establecer conexión. Los servicios integrados se incluyen con herramientas administradas por la plataforma y una directiva de servicio integrada, como una para bloquear las operaciones de escritura. Las administras mediante permisos en lugar de mediante la selección personalizada de herramientas o funciones de políticas.

Para Google Drive, Gmail, Google Calendar o Microsoft 365, estos servicios integrados controlan OAuth automáticamente, sin que se requiera ningún registro de aplicaciones.

Invocar un servicio MCP integrado

Accede a un servicio integrado a través de su URL de Unity AI Gateway, con el nombre completo en la ruta. Usa el nombre exactamente como aparece, con sus puntos y guiones bajos, y no lo codifiques en URL:

https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<mcp-service>

Para llamar al servicio desde el código del agente, haz que DatabricksMCPClient o un entorno de agentes apunten a esta URL. Consulta Usar servidores MCP en Agentes Personalizados.

Descubre las herramientas de un servicio y lee sus resultados

Cada Servicio MCP expone un conjunto diferente de herramientas, así que descúbrelas en tiempo de ejecución en lugar de codificar nombres de forma fija. Llama tools/list (o DatabricksMCPClient.list_tools()) para obtener el nombre, descripción y esquema de entrada de cada herramienta. Consulta Usar servidores MCP en Agentes Personalizados.

Lee el resultado de una llamada de herramienta desde el result campo. Su forma depende de si la herramienta define una salida estructurada:

• Salida escrita. Una herramienta puede anunciar un outputSchema y devolver un objeto JSON tipado en structuredContent. Cuando structuredContent esté presente, úsalo directamente. No necesita análisis sintáctico. Algunas herramientas de Azure Databricks, como las herramientas Genie, funcionan de esta manera.
• Salida de texto. Cuando no haya structuredContent, lee los bloques de texto en su lugar. El primer bloque contiene un documento JSON, así que analiza result.content[0].text como JSON.
• Ninguno. MCP no requiere un esquema de salida. Cuando una herramienta no define ninguno, inspecciona una respuesta de muestra para conocer sus campos de salida.

Por ejemplo, system.ai.google_calendar expone herramientas de lectura como calendar_event_list, cuyo resultado JSON tiene una items matriz de eventos (cada uno con id, summary, start, end, status, location, y enlaces). Las herramientas y los formatos de los resultados de un servicio distinto son totalmente diferentes, así que confírmalo siempre con tools/list y una llamada de muestra.

Registro de un servidor MCP externo

Para cualquier servidor MCP externo que no esté cubierto por OAuth gestionado o por los MCP Services proporcionados por Databricks, regístralo como un servicio MCP para poder administrarlo como un elemento protegible de Unity Catalog. Véase Registrar un servidor MCP externo.

Autenticación y seguridad

Azure Databricks usa servidores proxy de MCP administrados y conexiones HTTP del catálogo de Unity para controlar de forma segura la autenticación en servidores MCP externos.

• Autenticación de principal compartido: todos los usuarios comparten las mismas credenciales al acceder al servicio externo. Esto incluye el token portador, OAuth máquina a máquina (M2M) y autenticación compartida de usuario a máquina con OAuth. Úselo cuando el servicio externo no requiera acceso específico del usuario o cuando una sola cuenta de servicio sea suficiente.
• Autenticación por usuario (OAuth U2M por usuario): cada usuario se autentica con sus propias credenciales. El servicio externo recibe solicitudes en nombre del usuario individual, lo que permite el control de acceso específico del usuario, la auditoría y la responsabilidad. Úselo al acceder a recursos específicos del usuario, como repositorios de GitHub de un usuario, mensajes de Slack o calendario.

Azure Databricks controla los flujos de OAuth y la actualización de tokens, por lo que los usuarios finales no ven tokens. Puedes ver y administrar tus conexiones externas de MCP junto con tus endpoints de LLM desde Unity AI Gateway. Para obtener instrucciones de configuración detalladas para cada método de autenticación, consulte Conexiones HTTP.

Habilitar el acceso por usuario (acceso en nombre del usuario)

Algunos servicios leen datos que pertenecen a un usuario específico, como su calendario o correo electrónico. Para estos servicios, usa OAuth por usuario para que cada llamada se ejecute como el usuario que la realizó, no como una identidad compartida. Esto se aplica a servicios integrados system.ai.* como system.ai.google_calendar, system.ai.gmail, y system.ai.microsoft_365, y a servicios externos que registras con autenticación por usuario.

Para configurar el acceso en nombre de un agente:

1. Asegúrate de que el usuario que llama pueda invocar el servicio. Invocar cualquier Servicio MCP requiere dos cosas:

   • EXECUTE en el servicio.
   • USE CATALOG y USE SCHEMA en su catálogo y esquema principal. EXECUTE por sí solo no es suficiente, porque el Catálogo de Unity también comprueba la cadena madre ( véase Conceder acceso a compañeros de equipo).

   Cómo concedes estos datos depende del servicio:

   • Servicios integrados system.ai.* : Los usuarios de la cuenta ya tienen estos privilegios activados system y system.ai por defecto, así que normalmente no necesitas conceder nada.
   • Servicios personalizados en tu propio catálogo y esquema: Concede al usuario o grupo que realiza la llamada los permisos adecuados (no solo a la entidad de servicio de la aplicación) desde la pestaña Permisos de cada objeto protegible en el Explorador de catálogos, o con la API de REST. SQL DDL no está disponible para los servicios MCP.

   Para conceder acceso con la API de REST, sustituye <catalog>.<schema>.<service> por el tuyo propio:

   databricks api patch "/api/2.1/unity-catalog/permissions/mcp_service/<catalog>.<schema>.<service>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["EXECUTE"] } ] }'
   databricks api patch "/api/2.1/unity-catalog/permissions/catalog/<catalog>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["USE_CATALOG"] } ] }'
   databricks api patch "/api/2.1/unity-catalog/permissions/schema/<catalog>.<schema>" \
     --json '{ "changes": [ { "principal": "data-team", "add": ["USE_SCHEMA"] } ] }'
   

2. Añade el alcance de la ai-gateway API de usuario a tu app para que el token de usuario reenviado pueda llegar al servicio. Declara user_api_scopes: [ai-gateway] en el recurso de la app y llama al servicio con el cliente por usuario (get_user_workspace_client()). Consulta Autenticar a los servicios MCP y crear un agente y desplegarlo en las aplicaciones de Databricks.

3. Cada usuario da su consentimiento una vez. La primera vez que un usuario llama al servicio, debe completar un inicio de sesión OAuth único. Tu aplicación recibe un enlace de inicio de sesión para mostrar al usuario, o el usuario puede abrir el servicio en el Explorador de Catálogos y hacer clic en Iniciar Sesión.

Limitations

Las siguientes limitaciones se aplican a los servicios MCP:

• SQL DDL para MCP Services (por ejemplo, CREATE MCP SERVICE) no está disponible. Cree y administre servicios MCP con la interfaz de usuario o la API REST.
• Solo puede registrar servidores MCP externos como su propio servicio MCP. Actualmente no es compatible registrar fuentes de entidades de Genie, Apps o Unity Catalog como servicio MCP. Azure Databricks también proporciona servicios MCP integrados para aplicaciones SaaS comunes.
• La selección de herramientas admite prefijos (get_*) y patrones de coincidencia exacta. No se admiten patrones de exclusión (por ejemplo, !delete_*).
• La búsqueda global del catálogo de Unity no muestra los servicios MCP.

Las conexiones de servidor MCP externas también tienen las siguientes limitaciones:

• Los servidores MCP externos solo están disponibles en regiones en las que se admite Model Serving, incluido el uso en AI Playground, Genie Code y Chat en Genie. Consulte la disponibilidad de características de servicio de modelos.

Pasos siguientes

• Registre un servidor MCP externo para registrar e invocar un servidor MCP externo.
• Controle un servicio MCP para restringir las herramientas y aplicar directivas de servicio.
• Utiliza servidores MCP en Agentes Personalizados para llamar programáticamente a un Servicio MCP desde código de agentes, con ejemplos para el SDK de Agentes OpenAI, LangGraph y Servicio de Modelos.
• Conecte MCP a asistentes de IA y agentes de codificación para conectar agentes de codificación y asistentes de IA.
• Monitoriza toda la actividad de IA usando la tabla de trazados unificada para monitorizar, depurar y auditar toda la actividad del MCP desde un solo lugar.
• Gobernanza de inteligencia artificial con Unity AI Gateway para controlar los servidores MCP y los puntos de conexión LLM desde una ubicación central.