Connecter des clients non-Databricks aux serveurs Databricks MCP

Connectez des clients non Databricks (externes), des assistants IA et des IDE qui prennent en charge le protocole MCP (Model Context Protocol) aux serveurs MCP Databricks. Cela permet d’accéder directement aux données et outils Databricks dans votre environnement de développement.

En connectant des clients externes à des serveurs MCP Databricks, vous pouvez :

• Accéder aux fonctions de catalogue Unity, aux tables et aux index vectoriels à partir de votre ASSISTANT IDE ou IA
• Interroger des données Databricks directement à partir de Claude, Cursor, Replit ou d’autres outils MCP.

Prerequisites

• URL de serveur : obtenez les URL de serveur appropriées pour le serveur MCP Databricks que vous souhaitez utiliser :
  • Serveurs MCP gérés
  • Serveurs MCP externes
  • Serveurs MCP personnalisés
• Accès aux ressources : vérifiez que votre compte a accès aux ressources du catalogue Unity que vous souhaitez utiliser
• Accès réseau : si votre espace de travail a des restrictions d’adresse IP, autorisez la liste des adresses IP de votre client

Méthodes d’authentification

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

Connecter des clients à l’aide de l’authentification OAuth

OAuth fournit une authentification sécurisée avec des autorisations limitées et l’actualisation automatique des jetons.

Obtenir 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 sont les suivants :

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

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

Créer l’application Databricks OAuth

Un administrateur de compte crée une application Databricks OAuth. Récupérez son ID client et, si votre client l’exige, la clé secrète client.

Basé sur l’interface utilisateur (console de compte)

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

1. Dans la console de compte Databricks, accédez à Paramètres>App Connections>Add connection.

2. Configurez les paramètres de l’application :

   • Nom : entrez 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 un navigateur, mobile), décochez Générer une clé secrète client. Pour les clients confidentiels (côté serveur), vérifiez-le.
   • Étendues : Configurer les étendues d’API (voir Configurer les étendues OAuth ci-dessous)
   • Expiration du jeton : Définir l’accès au jeton approprié et les heures d’actualisation

Interface de ligne de commande (CLI)

Créez une application Databricks OAuth à l’aide de l’interface CLI Databricks :

databricks account custom-app-integration create --json '{
  "name": "mcp-oauth-client",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

Remplacez <your-client-redirect-url> par l’URL de redirection réelle de votre client.

Configurer les scopes OAuth

Les étendues OAuth contrôlent les API Databricks auxquelles votre client peut accéder. Pour la plupart des cas d’usage, utilisez l’étendue all-apis , qui accorde l’accès à toutes les API Databricks et est l’option la plus simple.

Pour un contrôle plus granulaire, vous pouvez spécifier des périmètres spécifiques à MCP au lieu de all-apis:

Pour plus d’informations sur la déclaration d’étendues d’API REST et leur utilisation avec des agents, consultez Déclarer des étendues d’API REST lors de la journalisation de l’agent.

Configurer l’accès réseau (facultatif)

Si votre espace de travail Databricks a des restrictions d’accès IP, ajoutez les adresses IP sortantes de votre client à la liste d'autorisation de l’espace de travail. Sinon, l’espace de travail bloque les demandes d’authentification de votre client. Consultez Gérer les listes d’accès IP.

Configurer votre client

Après avoir créé l’application OAuth dans Databricks, configurez votre client MCP spécifique avec les informations d’identification OAuth. Chaque client a sa propre méthode de configuration. Consultez les exemples spécifiques à la plateforme suivants pour obtenir des instructions détaillées pour 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 OAuth génériques de la section précédente, puis utilisez ces exemples pour configurer votre client spécifique.

Inspecteur MCP

L’inspecteur MCP est un outil de développement pour tester et déboguer des serveurs MCP.

Suivez la configuration de l’authentification OAuth ci-dessus avec les paramètres spécifiques à l’inspecteur suivants :

• URL de redirection :
  • http://localhost:6274/oauth/callback
  • http://localhost:6274/oauth/callback/debug
• Type de client : Public ( décochez Générer une clé secrète client)

Configurer l’inspecteur MCP :

1. Exécutez l’inspecteur : npx @modelcontextprotocol/inspector.
2. Définissez le type de transport sur Streamable HTTP.
3. Entrez l’URL de votre serveur Databricks MCP.
4. Dans la section Authentification , ajoutez votre ID client OAuth.
5. Cliquez sur Ouvrir les paramètres d’authentification et choisissez un flux Guidé ou Rapide.
6. Une fois l’authentification réussie, collez le jeton d’accès dans jeton du porteur sous la section Authentification du jeton d’API .
7. Cliquez sur Se connecter.

Connecteurs Claude

Connectez Claude aux serveurs MCP gérés et externes Databricks à l'aide de Claude Connectors et MCP distant.

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

• URL de redirection : https://claude.ai/api/mcp/auth_callback et https://claude.com/api/mcp/auth_callback
• Liste d’adresses IP autorisées (si nécessaire) : ajouter les adresses IP sortantes de Claude

Configurer Claude :

1. Accédez à Paramètres >Connecteurs dans Claude.
2. Cliquez sur Ajouter un connecteur personnalisé.
3. Entrez l’URL de votre serveur Databricks MCP.
4. Entrez l’ID client de votre application OAuth.
5. Cliquez sur Ajouter pour terminer.

Curseur/Planche à voile

Pour connecter en toute sécurité un IDE local tel que Cursor ou Planche à voile à un serveur Databricks MCP, utilisez-le mcp-remote avec OAuth. Suivez les instructions du dépôt mcp-remote pour configurer mcp-remote. Suivez ensuite la configuration de l’authentification OAuth pour vous assurer que votre OAuth est configuré correctement.

Configurer cursor ou Planche à voile :

1. Recherchez votre fichier de configuration MCP :

   • Curseur : ~/.cursor/mcp.json
   • Planche à voile : ~/.codeium/windsurf/mcp_config.json

2. Dans votre fichier de configuration, ajoutez votre serveur MCP :

   Pour les clients OAuth confidentiels (avec secret client) :

   {
     "mcpServers": {
       "databricks-mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
           "--static-oauth-client-info",
           "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
         ]
       }
     }
   }
   

   Pour les clients OAuth publics (sans clé secrète client) :

   {
     "mcpServers": {
       "databricks-mcp-server": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
           "--static-oauth-client-info",
           "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\" }"
         ]
       }
     }
   }
   

3. Remplacez <your-workspace-hostname> par le nom d’hôte de votre espace de travail Databricks.

4. Définissez la variable MCP_REMOTE_CLIENT_ID d’environnement avec votre ID client OAuth. Pour les clients confidentiels, définissez également MCP_REMOTE_CLIENT_SECRET avec votre secret client.

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

Les jetons d’accès personnels fournissent une méthode d’authentification plus simple qui convient au développement, au test et à l’accès à court terme aux serveurs MCP Databricks.

1. Générez un jeton d’accès personnel dans votre espace de travail Databricks. Consultez S'authentifier avec des jetons d’accès personnels Azure Databricks (hérités).

2. Configurer l’accès réseau (facultatif).

   Si votre espace de travail Databricks a des restrictions d’accès IP, ajoutez les adresses IP sortantes de votre client à la liste verte. 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 protocole PAT, configurez votre client MCP pour l’utiliser pour l’authentification. Chaque client a sa propre méthode de configuration. Consultez les exemples spécifiques à la plateforme ci-dessous pour obtenir des instructions détaillées pour les clients MCP populaires.

Exemples PAT

Les exemples suivants montrent comment configurer des clients MCP spécifiques avec l’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

Cursor prend en charge MCP par le biais de sa configuration de paramètres.

1. Ouvrez vos paramètres de curseur.

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

   {
     "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 nom d’hôte de votre espace de travail Databricks.

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

Claude Desktop

Claude Desktop peut se connecter aux serveurs MCP Databricks à l’aide de mcp-remote.

1. Recherchez votre claude_desktop_config.json fichier :

   • macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows : %APPDATA%\Claude\claude_desktop_config.json

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

   {
     "mcpServers": {
       "uc-function-mcp": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
           "--header",
           "Authorization: Bearer <YOUR_TOKEN>"
         ]
       }
     }
   }
   

3. Remplacez <your-workspace-hostname> par le nom d’hôte de votre espace de travail Databricks.

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

5. Redémarrez Claude Desktop pour que les modifications prennent effet.

Replit

Replit prend en charge la connexion à des serveurs MCP Databricks via une configuration de serveur MCP personnalisée.

1. Dans votre espace de travail Replit, cliquez sur Ajouter un serveur MCP.

2. Entrez votre URL de serveur Databricks MCP, par exemple :

   https://<your-workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}
   

3. Ajoutez un en-tête personnalisé :

   • Clé : Authorization
   • Valeur : Bearer <YOUR_TOKEN>

Consultez la documentation Replit MCP.

Limites

• Inscription dynamique du client : Databricks ne prend pas en charge les flux OAuth d’inscription de client dynamique pour les serveurs MCP managés, externes ou personnalisés. Les clients externes et les IDE qui imposent l’inscription dynamique du client ne sont pas pris en charge à l’aide de l’authentification OAuth.
• Prise en charge des jetons d’accès personnels du serveur MCP personnalisé : les serveurs MCP personnalisés hébergés sur Databricks Apps ne prennent pas en charge les jetons d’accès personnels pour l’authentification.
• Autorisation pour le compte : les serveurs MCP personnalisés hébergés sur Databricks Apps ne prennent pas en charge l'autorisation pour le compte de l'utilisateur.

Étapes suivantes

• Utiliser des serveurs MCP managés pour connecter des agents aux données du catalogue Unity
• Utiliser des serveurs MCP externes pour accéder aux services tiers
• Héberger des serveurs MCP personnalisés pour des outils spécifiques à l’organisation