Connecter des agents à des outils tiers avec les services MCP

Un service MCP est un catalogue Unity sécurisable qui inscrit un serveur MCP externe et régit la façon dont les agents l’utilisent. Vous l’appelez par son nom à trois niveaux, catalog.schema.mcp_service, et l’invoquez via Unity Gateway, le plan de contrôle pour gouverner le trafic IA.

L’inscription d’un serveur MCP en tant que catalogue Unity sécurisable signifie que vous la gérez avec les mêmes primitives que celles qui protègent vos autres ressources de catalogue Unity. Il s’agit notamment des subventions permettant de contrôler qui peut l’appeler, la sélection d’outils pour limiter les outils qu’il expose, les stratégies de service permettant d’autoriser ou de refuser des appels d’outils individuels, ainsi que la journalisation de l’audit et de l’utilisation pour suivre chaque appel.

Il existe deux façons d’utiliser les services MCP :

Exigences

• Un espace de travail activé pour le catalogue Unity.

• Espace de travail dans une région où Model Service est pris en charge. Consultez Disponibilité des fonctionnalités de service de modèles.

Fonctionnement

Un agent appelle un service MCP par son URL de passerelle Unity, et chaque appel suit le même chemin gouverné :

1. Invoke : L'agent envoie une requête MCP à l'URL Unity Gateway du service, authentifiée avec l'identité Azure Databricks de l'appelant.
2. Autoriser et gérer : la passerelle vérifie que l’appelant a EXECUTE sur le service MCP dans Unity Catalog. Le service expose uniquement les outils que vous avez sélectionnés et évalue toute stratégie de service jointe, qui peut autoriser, refuser ou exiger l’approbation de l’appel.
3. Proxy avec informations d’identification managées : la requête est transférée au serveur MCP externe via la connexion HTTP du service. Azure Databricks stocke les informations d’identification et gère les flux OAuth et l’actualisation des jetons, de sorte que l’agent ne les voit jamais.
4. Journalisation de l’utilisation, de l’audit et des traces : chaque appel est enregistré dans les tables système, ce qui vous permet de surveiller l’utilisation et d’auditer l’activité au fil du temps.

Services MCP fournis par Databricks

Azure Databricks fournit des services MCP prêts à l’emploi dans le system.ai schéma pour les applications SaaS courantes, afin que les agents puissent atteindre ces outils sans héberger ou inscrire votre propre serveur MCP. Chacun est un service MCP intégré que vous adressez par son nom de catalogue Unity. Pour donner accès à un agent, accordez EXECUTE sur le service (par exemple, system.ai.github). Aucune connexion requise. Les services intégrés sont fournis avec des outils gérés par la plateforme et une stratégie de service intégrée, par exemple pour bloquer les opérations d’écriture. Vous les régissez avec des subventions plutôt qu’avec des fonctions personnalisées de sélection d’outils ou de stratégie.

Pour Google Drive, Gmail, Google Calendar ou Microsoft 365, ces services intégrés gèrent OAuth pour vous, sans inscription d’application requise.

Invoquer un service MCP intégré

Adresser un service intégré par son URL de passerelle Unity, avec le nom entièrement qualifié dans le chemin. Utilisez le nom exactement comme il apparaît, avec ses points et ses sous-entendus, et ne l’encodez pas par URL :

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

Pour appeler le service depuis le code de l’assistant, pointez un DatabricksMCPClient ou un Agent Framework vers cette URL. Voir Utiliser les serveurs MCP dans les Agents personnalisés.

Découvrez les outils d’un service et lisez ses résultats

Chaque service MCP expose un ensemble différent d’outils, donc découvrez-les à l’exécution au lieu de coder des noms en dur. Appelez tools/list (ou DatabricksMCPClient.list_tools()) pour obtenir le nom, la description et le schéma d’entrée de chaque outil. Voir Utiliser les serveurs MCP dans les Agents personnalisés.

Lisez le résultat d’un appel à un outil dans le champ result. Sa forme dépend du fait que l’outil définisse ou non une sortie structurée :

• Sortie saisie. Un outil peut annoncer un outputSchema et renvoyer un objet JSON typé dans structuredContent. Lorsque structuredContent est présent, utilisez-le directement. Il n’a pas besoin d’analyse. Certains outils Azure Databricks, comme les outils Genie, fonctionnent ainsi.
• Sortie texte. Lorsqu’il n’y a pas de structuredContent, lisez plutôt les blocs de texte. Le premier bloc contient un document JSON, donc analysez result.content[0].text en JSON.
• Ni l’un ni l’autre. MCP ne nécessite pas de schéma de sortie. Lorsqu’un outil n’en définit aucun, inspectez une réponse d’exemple pour connaître ses champs de sortie.

Par exemple, system.ai.google_calendar expose des outils de lecture tels que calendar_event_list, dont le résultat JSON comporte un items tableau d’événements (chacun avec id, summary, start, end, status, location, et des liens). Les outils et le format des résultats d’un autre service sont entièrement différents ; confirmez-le donc toujours avec tools/list et un exemple d’appel.

Inscrire un serveur MCP externe

Pour tout serveur MCP externe non couvert par OAuth géré ou les services MCP fournis par Databricks, enregistrez-le comme un service MCP pour le gouverner comme un Unity Catalog sécurisé. Voir Enregistrer un serveur MCP externe.

Authentification et sécurité

Azure Databricks utilise des proxys MCP managés et des connexions HTTP du catalogue Unity pour gérer en toute sécurité l’authentification auprès de serveurs MCP externes.

• Authentification partagée du principal : tous les utilisateurs partagent les mêmes identifiants lors de l’accès au service externe. Cela inclut le jeton d'accès de détenteur, l’authentification OAuth Machine-to-Machine (M2M) et l’authentification partagée utilisateur-à-machine OAuth. Utilisez cette option lorsque le service externe ne nécessite pas d’accès spécifique à l’utilisateur ou lorsqu’un seul compte de service est suffisant.
• Authentification par utilisateur (OAuth U2M par utilisateur) : chaque utilisateur s’authentifie avec ses propres informations d’identification. Le service externe reçoit des demandes pour le compte de l’utilisateur individuel, en activant le contrôle d’accès, l’audit et la responsabilité spécifiques à l’utilisateur. Utilisez-le lors de l'accès à des ressources spécifiques à l'utilisateur, telles que les dépôts GitHub utilisateur, les messages Slack ou le calendrier.

Azure Databricks gère les flux OAuth et l'actualisation des jetons, de sorte que les utilisateurs finaux ne voient pas de jetons. Vous consultez et gérez vos connexions MCP externes en même temps que vos terminaux LLM depuis Unity Gateway. Pour obtenir des instructions de configuration détaillées pour chaque méthode d’authentification, consultez les connexions HTTP.

Activer l’accès par utilisateur (au nom de l’utilisateur)

Certains services lisent des données appartenant à un utilisateur spécifique, comme leur calendrier ou leur e-mail. Pour ces services, utilisez un OAuth par utilisateur afin que chaque appel s’exécute comme l’utilisateur qui l’a fait, et non comme une identité partagée. Cela s’applique aux services intégrés system.ai.* comme system.ai.google_calendar, system.ai.gmail, et system.ai.microsoft_365, ainsi qu’aux services externes que vous enregistrez avec une autologie par utilisateur.

Pour configurer un accès pour le compte d’un agent :

1. Assurez-vous que l’utilisateur appelant peut invoquer le service. Invoquer un service MCP nécessite deux choses :

   • EXECUTE sur le service.
   • USE CATALOG et USE SCHEMA sur le catalogue et le schéma parent. EXECUTE à lui seul ne suffit pas, car Unity Catalog vérifie aussi la hiérarchie parente (voir Accorder l’accès aux collègues).

   La manière dont vous accordez ces mesures dépend du service :

   • Services intégrés system.ai.* : Les utilisateurs de compte détiennent déjà ces privilèges activés system et system.ai par défaut, donc vous n’avez généralement pas besoin d’accorder quoi que ce soit.
   • Services personnalisés dans votre propre catalogue et schéma : accordez à l’utilisateur ou au groupe appelant les autorisations appropriées (pas uniquement au principal de service de l’application) à partir de l’onglet Autorisations de chaque élément sécurisable dans l’explorateur de catalogues, ou via l’API REST. SQL DDL n’est pas disponible pour les services MCP.

   Pour accorder l’accès avec l’API REST, remplacez <catalog>.<schema>.<service> :

   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. Ajoutez la portée de l’API ai-gateway utilisateur à votre application afin que le jeton utilisateur redirigé puisse atteindre le service. Déclarez user_api_scopes: [ai-gateway] au niveau de la ressource de l’application, et appelez le service avec le client propre à chaque utilisateur (get_user_workspace_client()). Voir Authentifier auprès des services MCP et créer un agent et le déployer sur Databricks Apps.

3. Chaque utilisateur consent une fois. La première fois qu’un utilisateur appelle le service, il doit effectuer une connexion OAuth à une seule fois. Votre application reçoit un lien de connexion pour afficher l’utilisateur, ou celui-ci peut ouvrir le service dans l’Explorateur de catalogue et cliquer sur Connexion.

Limitations

Les limitations suivantes s’appliquent aux services MCP :

• Sql DDL pour les services MCP (par exemple, CREATE MCP SERVICE) n’est pas disponible. Créez et gérez les services MCP avec l’interface utilisateur ou l’API REST.
• Vous pouvez inscrire uniquement des serveurs MCP externes en tant que votre propre service MCP. L’enregistrement de sources Genie, Apps ou d’entités Unity Catalog en tant que service MCP n’est actuellement pas pris en charge. Azure Databricks fournit également des services MCP intégrés pour les applications SaaS courantes.
• La sélection de l’outil prend en charge les modèles de préfixe (get_*) et de correspondance exacte. Les modèles d’exclusion (par exemple) !delete_*ne sont pas pris en charge.
• La recherche globale du catalogue Unity ne surface pas les services MCP.

Les connexions de serveur MCP externes présentent également les limitations suivantes :

• Les serveurs MCP externes sont disponibles uniquement dans les régions où Model Serving est pris en charge, notamment l’utilisation dans AI Playground, Genie Code et Chat dans Genie. Consultez Disponibilité des fonctionnalités de service de modèles.

Étapes suivantes

• Enregistrez un serveur MCP externe pour enregistrer et appeler un serveur MCP externe.
• Gouverner un service MCP pour restreindre les outils et appliquer des stratégies de service.
• Utilisez les serveurs MCP dans les agents personnalisés pour appeler un service MCP de manière programmatique à partir du code de l’agent, avec des exemples pour le SDK OpenAI Agents, LangGraph et Model Serving.
• Connectez les mcPs aux assistants IA et aux agents de codage pour connecter des agents de codage et des assistants IA.
• Surveillez toute l’activité de l’IA à l’aide de la table de trace unifiée pour surveiller, déboguer et auditer toutes les activités MCP à partir d’un seul endroit.
• Gouvernance de l’IA avec Unity Gateway pour gouverner les serveurs MCP et les terminaux LLM depuis un emplacement central.