Aller au contenu principal
Dernière mise à jour le

Connecter Claude Code

Utilisez Claude Code ou l'application de bureau Claude avec des modèles, des outils MCP et des compétences via Unity Gateway. Pour Claude Code, utilisez le protocole Unity Gateway CLI (ug) ou configurez la connexion manuellement. Pour l’application de bureau, configurez la connexion dans les paramètres de l’application.

Pour connecter des outils à une configuration Claude Code existante, accédez à Ajouter des outils MCP. Pour Claude sur le Web ou lors d'une session de bureau utilisant votre compte Claude, utilisez les connecteurs Claude.

Prérequis​

Vous avez besoin de l’URL de votre workspace Databricks et de l’accès aux modèles que vous souhaitez utiliser. Pour la configuration sur ordinateur, installez la dernière application de bureau Claude et demandez à l’administrateur de votre compte de vous fournir un identifiant client OAuth, comme décrit ci-dessous.

Si votre administrateur a déjà configuré votre appareil, suivez les instructions de connexion et de lancement de votre organisation.

Claude Code​

Utilisez la CLI Unity Gateway (recommandé)​

Installez ug, puis exécutez cette commande depuis le répertoire de votre projet :

Bash
ug claude

Suivez les instructions pour sélectionner votre Workspace et vous connecter. ug configure la connexion et ouvre Claude Code dans votre terminal. Start à travailler avec les mêmes invites et commandes que vous utilisez déjà. Pour changer de modèle, saisissez /model.

Continuez sur Ajouter des outils MCP pour connecter des données et des services. Pour download les compétences partagées, exécutez ug skills add et sélectionnez les compétences de votre choix. Reportez-vous à la section Ajouter des outils et des compétences pour afficher plus d'options.

Configurez Claude Code manuellement​

Merge les paramètres suivants dans ~/.claude/settings.json:

JSON
{
  "env": {
    "ANTHROPIC_MODEL": "<model-api-name>",
    "ANTHROPIC_BASE_URL": "https://<workspace-hostname>/ai-gateway/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<databricks-personal-access-token>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-databricks-use-coding-agent-mode: true",
    "CLAUDE_CODE_USE_GATEWAY": "1",
    "ENABLE_PROMPT_CACHING_1H": "1",
    "ENABLE_TOOL_SEARCH": "true"
  }
}

Remplacez <workspace-hostname> par le hostname de votre workspace, sans https://. Définissez <model-api-name> sur le nom Unity Catalog complet d’une API de modèle Claude à laquelle vous avez accès, et fournissez votre jeton d’accès personnel Databricks.

Run claude from your project directory. For other settings, see Claude Code settings.

Ajouter des outils MCP​

Pour utiliser system.ai.dbsql, system.ai.sandbox ou system.ai.web_search, un administrateur de compte doit activer la version bêta de Unity Gateway depuis la page Previews de la console du compte. Consultez Gérer les aperçus du compte.

  1. Ouvrez Unity Gateway > MCPs dans votre workspace. Choisissez un MCP intégré ou enregistrez votre serveur MCP externe.

  2. Copier le nom complet du MCP, tel que system.ai.github ou <catalog>.<schema>.<service>.

  3. Confirmez que vous disposez d’un accès au MCP.

  4. Après l'installation de ug, ajoutez le MCP à Claude Code :

    Bash
    ug mcp add --agents claude --names <catalog>.<schema>.<service>

    Remplacez l'espace réservé par le nom que vous avez copié. Par exemple, utilisez --names system.ai.github pour GitHub. Pour choisir les services de manière interactive, omettez --names.

Lors de la première configuration, suivez les instructions pour sélectionner votre Workspace, vous connecter et choisir un modèle. ug configure l’accès au modèle et au MCP, et effectue le refresh des identifiants. Redémarrez Claude Code avec ug claude, puis testez un outil.

Ajouter des outils MCP manuellement​

Utilisez le client OAuth intégré ci-dessous ou configurez votre propre application OAuth. Pour ajouter un MCP avec le client intégré, exécutez :

Bash
claude mcp add --transport http --scope user \
  --client-id claude-code --callback-port 3118 \
  databricks-tools \
  "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service-name>"

Remplacez le hostname et le nom du MCP. Cette option utilise le client OAuth claude-code intégré. Ouvrez Claude Code, saisissez /mcp, puis connectez-vous au serveur avec votre compte Databricks. Répétez l’opération avec un nom de serveur différent pour chaque MCP que vous souhaitez ajouter, puis testez un outil.

Utilisez votre propre application OAuth

  1. Demandez à un administrateur de compte d’ouvrir Settings > App connections > Add connection dans la console du compte.

  2. Entrez un nom tel que claude-code-mcp, décochez Generate a client secret pour un client public, définissez l'URL de redirection sur http://localhost:8080/callback et sélectionnez le périmètre ai-gateway. Enregistrez et copiez le Client ID . Consultez Create an OAuth app.

  3. Enregistrez le MCP à l'aide de cet identifiant client et du port de rappel correspondant :

    Bash
    claude mcp add --transport http --scope user \
      --client-id <client-id> --callback-port 8080 \
      databricks-tools \
      "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>"

  4. Ouvrez Claude Code, saisissez /mcp et connectez-vous. Si votre organisation nécessite un client confidentiel, ajoutez --client-secret à la commande et saisissez le secret lorsque vous y êtes invité.

Tester un outil MCP​

  1. Dans Claude Code, saisissez /mcp et vérifiez que le serveur est connecté.
  2. Demandez à Claude de lister les outils de ce serveur, puis demandez une opération de lecture. Pour GitHub, demandez-lui de trouver un ticket (issue) dans un repository auquel vous avez accès. Pour un serveur personnalisé, utilisez un outil et des entrées que vous avez testés lors de l'enregistrement.
  3. If a tool call prompts you to sign in, open the login link returned by the MCP, complete provider consent, then retry the call.
  4. Vérifiez que Claude effectue un appel d’outil et renvoie son résultat. Une réponse textuelle ne suffit pas à vérifier la connexion.

Pour utiliser les données Databricks, connectez system.ai.genie_one_mcp pour les questions métiers ou system.ai.dbsql pour SQL. Par exemple, demandez au MCP SQL d'exécuter SELECT 1 AS result.

Pour en savoir plus sur les autorisations, les politiques et l’utilisation, consultez la page Govern an MCP.

Connecter les compétences manuellement​

Pour exposer les compétences Unity Gateway publiées en tant qu'outils, enregistrez le registre des compétences en tant que serveur HTTP MCP :

Bash
claude mcp add --transport http --scope user \
  --header "Authorization: Bearer <databricks-personal-access-token>" \
  databricks-skill-registry \
  "https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>"

Remplacez les placeholders par votre workspace, votre jeton et votre schéma de compétences. Conservez la barre oblique de fin avant ?schema. Pour inclure plusieurs schémas, répétez le parameter : ?schema=main.default&schema=ml.prod.

Restart Claude Code and check the connection with /mcp. Ask Claude to use a skill by its full name, such as Use <catalog>.<schema>.<skill-name> to review this query. This connection exposes skills as MCP tools; ug skills add download skills for native discovery instead.

Application de bureau Claude​

1. Obtenir un identifiant client OAuth​

Demandez à l'administrateur de votre compte de créer une connexion d'application OAuth. Dans la console de compte Databricks, ouvrez Settings > App connections > Add connection et utilisez :

Paramètre

Valeur

Type d’identité

Application standard

Nom de l'application

claude-desktop

Générer un secret client

Non cochée (client public)

URL de redirection

http://127.0.0.1:53180/callback

Périmètres d’accès

ai-gateway

Paramètre

Valeur

Type d’identité

Application standard

Nom de l'application

claude-desktop

Générer un secret client

Non cochée (client public)

URL de redirection

http://127.0.0.1:53180/callback

Périmètres d’accès

ai-gateway

Enregistrez la connexion et copiez l’identifiant Client ID . Si vous prévoyez de connecter des compétences, enregistrez également http://127.0.0.1:53280/callback.

2. Connect to Unity Gateway​

From the desktop app's sign-in screen, select Help > Troubleshooting > Enable Developer Mode , then Developer > Configure Third-Party Inference .

Sur la page Connection , sélectionnez Gateway et saisissez :

Paramètre

Valeur

Type d'identifiant

Connexion interactive

URL de base de la passerelle

https://<workspace-hostname>/ai-gateway/anthropic

ID client

Votre identifiant client OAuth

Issuer URL

https://<workspace-hostname>/oidc

Jeton Bearer

Jeton d’accès

Champs d'application

ai-gateway

Ajouter offline_access

Activé

Rediriger le port

53180

Paramètre

Valeur

Type d'identifiant

Connexion interactive

URL de base de la passerelle

https://<workspace-hostname>/ai-gateway/anthropic

ID client

Votre identifiant client OAuth

Issuer URL

https://<workspace-hostname>/oidc

Jeton Bearer

Jeton d’accès

Champs d'application

ai-gateway

Ajouter offline_access

Activé

Rediriger le port

53180

Remplacez <workspace-hostname> par le Hostname de votre Workspace Databricks. Conservez les autres paramètres par default. Consultez la configuration de la passerelle d’Anthropic pour obtenir des détails sur les champs.

Cliquez sur Test connection et connectez-vous à Databricks. Sélectionnez Apply Changes , puis Save & Restart . Sur l'écran de connexion, choisissez la configuration tierce et start une conversation dans Code ou Cowork .

3. Ajouter des outils et des compétences MCP​

Ouvrez Developer > Configure Third-Party Inference > Connectors . Sous Managed MCP servers , ajoutez une entrée pour chaque registre de compétences ou MCP que vous souhaitez utiliser.

Utilisez ces paramètres pour les deux types de connecteur :

Paramètre

Valeur

Transport

HTTP diffusable

OAuth

Utilisez votre propre client

ID client

Votre identifiant client OAuth

Secret du client

Laisser vide

Serveur d’autorisation

["https://<workspace-hostname>/oidc"]

Périmètre

ai-gateway

Demande offline_access

Activé

Hôte de rappel

127.0.0.1

Paramètre

Valeur

Transport

HTTP diffusable

OAuth

Utilisez votre propre client

ID client

Votre identifiant client OAuth

Secret du client

Laisser vide

Serveur d’autorisation

["https://<workspace-hostname>/oidc"]

Périmètre

ai-gateway

Demande offline_access

Activé

Hôte de rappel

127.0.0.1

Pour un MCP , recherchez son nom en trois parties sous Unity Gateway > MCPs dans votre workspace. Attribuez un nom descriptif au connecteur, définissez le Port de callback sur 53180, puis utilisez cette URL :

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

Pour les compétences , nommez le connecteur databricks-skill-registry, définissez le port de rappel sur 53280 et utilisez :

Text
https://<workspace-hostname>/ai-gateway/skills/?schema=<catalog>.<schema>

Keep the trailing slash before ?schema. To include multiple schemas, repeat the parameter: ?schema=main.default&schema=ml.prod. These skills are exposed to Claude as tools through the connector.

Pour chaque connecteur, cliquez sur Se connecter et tester et terminez la connexion. Sélectionnez Apply Changes , puis Save & Restart . Demandez à Claude d'utiliser un outil connecté ou une compétence par son nom complet. Consultez la section Ajouter des outils et des compétences pour connaître les conditions d'accès et afficher plus d'options.

Connecteurs Claude​

Pour system.ai.dbsql, activez d’abord la bêta de Unity Gateway.

Utilisez un connecteur personnalisé pour ajouter des outils MCP Databricks à Claude sur le Web ou sur le bureau à l'aide de votre compte Claude.

  1. Demandez à un administrateur de compte de créer un client OAuth. Pour un serveur MCP, sélectionnez la portée ai-gateway et enregistrez les deux URL de redirection :

    • https://claude.ai/api/mcp/auth_callback
    • https://claude.com/api/mcp/auth_callback

  2. Dans Claude, ouvrez Settings > Connectors > Add custom connector .

  3. Saisissez l'URL MCP :

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

  4. Saisissez l'ID client OAuth et, s'il s'agit d'un client confidentiel, son secret. Cliquez sur Ajouter et terminez la connexion.

  5. Dans une conversation, activez le connecteur et demandez à Claude d'appeler l'un de ses outils. Pour system.ai.dbsql, essayez SELECT 1 AS result.

Si votre workspace restreint les adresses IP entrantes, autorisez les adresses IP sortantes de Claude. Consultez la section Authentification et mise en réseau MCP pour en savoir plus sur les autorisations, la connexion au fournisseur et le dépannage.

Utiliser un jeton d'accès personnel dans Claude desktop pour les tests locaux

Cette option nécessite Node.js avec npx et un jeton d'accès personnel. Cela fonctionne pour les serveurs MCP fournis et enregistrés par Databricks, ainsi que pour les Endpoint de Workspace hérités. Les serveurs hébergés sur Databricks Apps nécessitent OAuth.

Merge this entry into claude_desktop_config.json at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows:

JSON
{
  "mcpServers": {
    "databricks-tools": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://<workspace-hostname>/ai-gateway/mcp-services/<catalog>.<schema>.<service>",
        "--header",
        "Authorization: Bearer <databricks-pat>"
      ]
    }
  }
}

Remplacez les espaces réservés, excluez les jetons du contrôle des sources et redémarrez Claude Desktop. Demandez à Claude d’appeler un outil en lecture seule pour vérifier la connexion.

Dépannage​

  • Claude Code ne se connecte pas : exécutez ug doctor si vous utilisez ug. Pour une configuration manuelle, vérifiez le hostname de votre workspace, votre jeton, le nom du modèle et les autorisations relatives au modèle.

  • Échec de la connexion au bureau : vérifiez l'ID client, l'émetteur /oidc et la portée ai-gateway. L’URL de redirection enregistrée doit correspondre à l'hôte et au port du connecteur : 53180 pour les modèles et les MCP, ou 53280 pour les compétences dans ce guide. Les modifications apportées à l'application OAuth peuvent prendre jusqu'à 30 minutes avant de prendre effet.

  • Un modèle de bureau est manquant : vérifiez les autorisations de votre modèle. Sous Connection > Models > Model list , ajoutez le nom complet du modèle Unity Catalog. Une liste explicite remplace la découverte automatique ; incluez donc tous les modèles que vous souhaitez utiliser. Appliquez les modifications et redémarrez.

  • Si un connecteur MCP ou de compétence échoue : vérifiez son URL et ses autorisations. Le champ Authorization server doit contenir le tableau JSON indiqué ci-dessus. Cliquez sur Se connecter & tester pour inspecter l'erreur.

  • La connexion au workspace fonctionne, mais un outil vous demande de vous connecter : ouvrez le lien de connexion renvoyé par le protocole MCP, connectez-vous au fournisseur externe, puis réessayez l'appel. La connexion au workspace et celle au fournisseur sont deux étapes distinctes.

  • Claude Code OAuth signale une non-correspondance de redirection ou un dépassement du délai d'attente de la connexion : Pour une application OAuth personnalisée, faites correspondre son URL de redirection à l'hôte et au port de rappel, et vérifiez l'accès réseau. Les modifications apportées aux applications OAuth peuvent prendre jusqu'à 30 minutes pour prendre effet.

Étapes suivantes​

Sur cette page