Aller au contenu principal
Dernière mise à jour le

Connectez des MCP aux assistants d’IA et aux agents de codage

remarque

Les MCP Databricks auxquels vous pouvez vous connecter en sont à différentes étapes de publication. Consultez les serveurs MCP gérés, les services MCP et les serveurs MCP hébergés par Databricks pour connaître l’étape actuelle de chaque fonctionnalité.

Connectez les clients, les assistants IA et les IDEs prenant en charge le protocole MCP (Model Context Protocol) aux serveurs MCP Databricks. Cela permet d'accéder aux données et aux outils Databricks directement dans votre environnement de développement.

En connectant des clients aux MCP Databricks, vous pouvez :

  • Accédez aux fonctions, tables et index vectoriels de Unity Catalog depuis votre IDE ou votre assistant IA
  • Query les données Databricks directement depuis Claude, Claude Code, Cursor, Replit ou d'autres outils compatibles MCP

Comment ça marche​

Chaque client se connecte aux MCP Databricks de la même manière : ajoutez l’URL du serveur à la configuration MCP du client, authentifiez-vous avec OAuth ou un jeton d’accès personnel, et le client appelle les outils via HTTP diffusable. L’URL détermine le MCP que vous atteignez : un serveur MCP géré pour les données et outils Unity Catalog, un service MCP pour les outils externes, ou votre propre serveur MCP hébergé par Databricks:

Un client MCP, tel que Claude, Claude Code, Cursor ou ChatGPT, est configuré avec une URL de serveur MCP Databricks, s'authentifie avec OAuth ou un jeton d'accès personnel, et appelle des outils via Streamable HTTP sur l'un des trois types d'endpoint : les données et le code Databricks via des serveurs MCP gérés ; des outils tiers comme GitHub et Slack via des services MCP ; ou votre propre serveur MCP hébergé sur Databricks Apps.

Exigences​

  • URL de serveur : Obtenez les URL de serveur appropriées pour le serveur MCP Databricks que vous souhaitez utiliser :

  • Accès aux ressources : vérifiez que vous avez accès aux serveurs MCP que vous souhaitez utiliser ainsi qu’à toutes les ressources sous-jacentes. Par exemple, si vous utilisez le serveur MCP géré par Genie, vous avez besoin d’un accès à Genie Agent sous-jacent.

  • Accès réseau : Si votre workspace Databricks comporte des restrictions d'accès IP, ajoutez les adresses IP sortantes de votre client à la liste d'autorisation pour lui permettre de se connecter à votre workspace :

    • Suivez la documentation relative aux listes d’accès IP du workspace et aux listes d’accès IP du compte pour vérifier si des restrictions sont en place
    • Si les listes d'accès IP sont activées, identifiez les adresses IP sortantes de votre client. Ces informations sont généralement disponibles dans la documentation client ; par exemple, Claude documente ses adresses IP sortantes ici.
    • Assurez-vous que les adresses IP sortantes de votre client sont ajoutées à la liste.

Méthodes d’authentification​

Choisissez la méthode d’authentification qui correspond le mieux à vos exigences de sécurité :

Méthode

Serveurs MCP gérés et services MCP

Serveur MCP hébergé sur Databricks

Niveau de sécurité

Idéal pour

OAuth (recommandé)

Pris en charge

Pris en charge

Élevé - autorisations à portée limitée, refresh automatique des jetons

Utilisation en production, environnements d’équipe, accès à long terme

Jetons d'accès personnels

Pris en charge

Non pris en charge

Moyen - accès par jeton avec expiration

Développement individuel, test, accès à court terme

Méthode

Serveurs MCP gérés et services MCP

Serveur MCP hébergé sur Databricks

Niveau de sécurité

Idéal pour

OAuth (recommandé)

Pris en charge

Pris en charge

Élevé - autorisations à portée limitée, refresh automatique des jetons

Utilisation en production, environnements d’équipe, accès à long terme

Jetons d'accès personnels

Pris en charge

Non pris en charge

Moyen - accès par jeton avec expiration

Développement individuel, test, accès à court terme

Connectez les clients à l’aide de l’authentification OAuth​

OAuth fournit une authentification sécurisée avec des autorisations à portée limitée et un refresh automatique des jetons.

remarque

Les serveurs MCP Databricks prennent en charge les deux types de clients conformément à la spécification d’autorisation MCP:

  • Clients publics : aucun secret client requis
  • Clients confidentiels : incluez le secret du client

Obtenez l'URL de redirection OAuth de votre client​

Chaque client MCP nécessite des URL de redirection OAuth spécifiques pour les rappels d’authentification. Les modèles d’URL de redirection courants incluent :

  • Clients Web : https://<domain>/oauth/callback ou https://<domain>/api/mcp/auth_callback
  • Outils de développement local : http://localhost:<port>/oauth/callback

Consultez la documentation de votre client pour trouver les URL de redirection exactes requises.

Créer l’application OAuth Databricks​

Demandez à un administrateur de compte de créer une application OAuth Databricks. Récupérez son identifiant client et, si votre client l'exige, le secret du client.

Créez une application OAuth Databricks à l’aide de la console de compte:

  1. Dans la console de compte Databricks, accédez à Settings > App Connections > Add connection .
  2. Configurez les paramètres de l'application :
    • Nom : saisissez un nom descriptif pour votre application OAuth (par exemple, claude-mcp-client, mcp-inspector)
    • URL de redirection : ajoutez les URL de redirection requises par votre client externe
    • Type de client : pour les clients publics (basés sur navigateur, mobiles), décochez Générer un secret client . Pour les clients confidentiels (côté serveur), laissez cette option cochée.
    • Champs d’application : configurez les champs d’application de l'API (consultez la référence des champs d’application d’OAuth Databricks pour les champs disponibles)
    • Expiration du jeton : définissez les durées d’accès et de refresh appropriées pour le jeton

Configurer l'accès réseau (facultatif)​

Si votre workspace Databricks a des restrictions d'accès IP, ajoutez les adresses IP sortantes de votre client à la liste d'autorisation du workspace. Dans le cas contraire, le workspace bloque les demandes d'authentification provenant de votre client. Voir Gérer les listes d'accès IP.

Configurez votre client​

Après avoir créé l’application OAuth dans Databricks, configurez votre client MCP spécifique avec les identifiants OAuth. Chaque client possède sa propre méthode de configuration. Consultez les exemples spécifiques à la plateforme suivants pour obtenir des instructions détaillées sur les clients MCP populaires.

Exemples OAuth​

Les exemples suivants montrent comment configurer des clients MCP spécifiques avec l’authentification OAuth. Suivez d’abord les étapes de configuration génériques d’OAuth décrites dans la section précédente, puis utilisez ces exemples pour configurer votre client spécifique.

Le MCP Inspector est un outil de développement destiné au test et au debugging des serveurs MCP.

Inspecteur MCP

Suivez la configuration de l'authentification OAuth ci-dessus avec ces paramètres spécifiques à l'Inspector :

  • URL de redirection :

    • http://localhost:6274/oauth/callback
    • http://localhost:6274/oauth/callback/debug

  • Type de client : Public (décochez Générer un secret client )

Configurer l’inspecteur MCP :

  1. Exécuter l'inspecteur : npx @modelcontextprotocol/inspector.
  2. Définissez Transport Type sur Streamable HTTP.
  3. Saisissez l'URL de votre serveur MCP Databricks.
  4. Dans la section Authentication , ajoutez votre ID client OAuth.
  5. Cliquez sur Open Auth Settings et choisissez le flux Guided ou Quick .
  6. Une fois l'authentification réussie, collez le jeton d'accès dans Bearer Token sous la section API Token Authentication .
  7. Cliquez sur **Connecter**.

Flux d’authentification de l’inspecteur MCP

Connecter des clients à l’aide de l’authentification par jeton d’accès personnel (PAT)​

Les jetons d’accès personnels offrent une méthode d’authentification plus simple, adaptée au développement individuel, aux tests et à l’accès à court terme aux serveurs MCP Databricks.

remarque

Les jetons d'accès personnels ne sont pris en charge que pour les serveurs MCP gérés et les services MCP. Les serveurs MCP hébergés par Databricks nécessitent une authentification OAuth.

Pour les services MCP, générez un jeton à partir de la page de détails du service :

  1. Dans votre Workspace, ouvrez le service MCP dans Catalog Explorer, ou accédez à AI Gateway > MCPs et sélectionnez le service.
  2. Dans Get started , cliquez sur Générer un jeton d'accès .
  3. Copiez la commande export DATABRICKS_TOKEN=... générée dans votre terminal. Le jeton est également ajouté aux exemples de requête sur la page.

Utilisez ce jeton pour les tests locaux et choisissez la durée de vie la plus courte qui convienne à votre flux de travail. Ne commit pas de jetons dans le contrôle de code source et ne les partagez pas dans les fichiers de configuration client. Pour les connexions client en production ou à l’échelle de l’équipe, utilisez OAuth au lieu d’un PAT.

  1. Générez un jeton d’accès personnel dans votre workspace Databricks. Voir S’authentifier avec des jetons d’accès personnel Databricks (hérité).

  2. Configurez l'accès réseau (facultatif).

    Si votre workspace Databricks comporte des restrictions d'accès IP, ajoutez les adresses IP sortantes de votre client à la liste d'autorisations. Consultez la documentation de votre client ou la configuration réseau de votre environnement de déploiement pour obtenir les adresses IP requises.

  3. Configurez votre client.

    Après avoir généré le PAT, configurez votre client MCP pour l'utiliser pour l'authentification. Chaque client possède sa propre méthode de configuration. Voir les exemples spécifiques à la plateforme ci-dessous pour des instructions détaillées sur les clients MCP populaires.

    Lorsqu’un client demande des en-têtes personnalisés, transmettez le jeton en tant que jeton Bearer dans l’en-tête Authorization : Authorization: Bearer <YOUR_TOKEN>.

Exemples de PAT​

Les exemples suivants montrent comment configurer des clients MCP spécifiques avec une authentification par jeton d'accès personnel. Suivez d'abord la configuration de l'authentification PAT ci-dessus, puis utilisez ces exemples pour configurer votre client spécifique.

Cursor prend en charge MCP via sa configuration de paramètres.

  1. Ouvrez vos paramètres Cursor.

  2. Ajoutez la configuration suivante (adaptez l'URL pour votre serveur MCP choisi) :

    JSON
    {
      "mcpServers": {
        "uc-function-mcp": {
          "type": "streamable-http",
          "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
          "headers": {
            "Authorization": "Bearer <YOUR_TOKEN>"
          },
          "note": "Databricks UC function"
        }
      }
    }

  3. Remplacez <your-workspace-hostname> par le hostname de votre workspace Databricks.

  4. Remplacez <YOUR_TOKEN> par votre jeton d'accès personnel.

Résoudre les problèmes de connexion​

Procédez comme suit pour diagnostiquer et résoudre les problèmes de connexion courants.

Valider l'authentification​

Vérifiez que vos identifiants d’authentification sont correctement configurés avant de tester la connexion.

Pour l'authentification OAuth utilisateur à machine (U2M), testez la connexion avec MCP Inspector. Le flux OAuth valide les informations d'identification pendant le processus de connexion.

Vérifier la configuration réseau​

Les restrictions réseau peuvent empêcher les clients externes de se connecter à votre workspace Databricks. Assurez-vous que toutes les politiques de liste d’accès IP Databricks sont configurées pour permettre à votre client de se connecter à votre compte et à votre workspace Databricks. Voir Exigences.

Identifier les problèmes de connexion spécifiques au client​

Essayez de vous connecter avec un client MCP différent pour voir si le problème persiste. Databricks recommande d'effectuer des tests avec le MCP Inspector. Si votre connexion fonctionne avec l'inspecteur MCP mais échoue avec votre client, le problème vient probablement de la configuration de votre client. Contactez le fournisseur du client pour obtenir de l'aide supplémentaire.

Signaler les problèmes à l’assistance Databricks​

Si vous continuez à rencontrer des problèmes de connexion après avoir effectué ces étapes de dépannage :

  1. Consultez les Logs de votre client MCP, tels que Claude, Cursor ou MCP Inspector, pour rechercher des messages d'erreur et des traces de pile.

  2. Collectez les informations de diagnostic suivantes :

    • Méthode d'authentification utilisée (OAuth ou PAT)
    • URL du serveur MCP
    • Messages d’erreur du client
    • Détails de la configuration réseau (restrictions IP, règles de pare-feu)

  3. Contactez l’assistance et partagez les informations de diagnostic pour résoudre le problème.

Limitations​

  • Enregistrement dynamique de client : Databricks ne prend pas en charge les flux OAuth d'enregistrement dynamique de client pour les serveurs MCP gérés, les services MCP ou les serveurs MCP hébergés par Databricks. Les clients externes et les IDEs qui imposent l'enregistrement dynamique de client ne sont pas pris en charge avec l'authentification OAuth.
  • Prise en charge des jetons d’accès personnel pour les serveurs MCP hébergés sur Databricks : les serveurs MCP que vous hébergez sur Databricks Apps ne prennent pas en charge les jetons d’accès personnel pour l’authentification.

Ressources supplémentaires​

Sur cette page