Aller au contenu principal
Dernière mise à jour le

Connecter Claude Code

Utilisez Claude Code avec des modèles, des outils MCP et des compétences via Unity Gateway. Utilisez Unity Gateway CLI (ug) pour configurer l'accès ou configurez la connexion manuellement.

Pour connecter des outils à une configuration Claude Code existante, allez sur Ajouter des outils MCP.

Prérequis​

Vous avez besoin de votre URL de workspace Databricks, d'un accès aux modèles que vous souhaitez utiliser et de la version la plus récente de Claude Code.

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

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.

Mode automatique​

Le mode automatique réduit le nombre d’invites d’autorisation routinières en vérifiant les appels d’outils proposés avec un classificateur de sécurité.

Les modèles Anthropic via Unity Gateway utilisent les vérifications automatiques natives d’Anthropic. Pour les modèles de fondation non Anthropic hébergés par Databricks qui prennent en charge l’appel de fonction, Unity Gateway fournit le classifieur. Pour consulter la liste des modèles pris en charge et leurs capacités respectives, consultez la page Modèles disponibles via Databricks.

Claude Code évalue les règles permissions.deny explicites et les règles permissions.ask étendues au contenu avant de consulter le classifieur. Une règle de refus correspondante bloque l’action, et une règle de demande correspondante nécessite une invite d’autorisation. Le mode auto peut aussi bloquer des actions en fonction de la conversation et des règles du classifieur, ou lorsqu’une vérification ne peut pas produire de verdict valide.

Après avoir configuré votre connexion avec ug, start Claude Code en mode automatique :

Bash
ug claude -- --permission-mode auto

Avec une connexion manuelle, exécutez claude --permission-mode auto. Pour le transfert d’arguments ug, consultez la documentation de la CLI ug.

Configurer une infrastructure de confiance​

Décrivez les repository, domaines et services approuvés de votre organisation dans autoMode.environment. Ces entrées aident le classificateur à distinguer l’accès attendu à votre infrastructure des actions qu’il doit bloquer. Merge un bloc autoMode dans vos paramètres utilisateur sur ~/.claude/settings.json, par exemple :

JSON
{
  "autoMode": {
    "environment": [
      "$defaults",
      "Source control: github.example.com/example-org and its repositories",
      "Trusted internal services: builds.internal.example.com"
    ]
  }
}

Remplacez les entrées exemple par l'infrastructure de votre organisation. Les entrées sont des descriptions en langage naturel. Gardez "$defaults" pour conserver les entrées d'environnement intégrées lorsque vous ajoutez les vôtres.

Le classifieur lit autoMode dans les paramètres utilisateur, les paramètres gérés ou la configuration --settings en ligne. Il ne lit pas ce bloc à partir du projet .claude/settings.json ou .claude/settings.local.json. Les administrateurs peuvent distribuer la configuration partagée via les paramètres gérés.

Pour la personnalisation des règles, les paramètres gérés et l’examen des actions bloquées, consultez Configurer le mode automatique.

Suivre l’utilisation du classifieur​

Les vérifications Unity Gateway envoient les arguments d’outil proposés et le contexte de conversation à un modèle de classificateur distinct. Les demandes de classificateur entraînent des frais de modèle supplémentaires et peuvent ajouter de la latence.

Les demandes de classification apparaissent dans system.ai_gateway.usage avec invocation_metadata.source défini sur SAFEGUARD_CLASSIFIER. Utilisez cette valeur pour distinguer les demandes de vérification de sécurité, leur utilisation des jetons et leur latence des demandes de votre modèle de codage. Consultez Suivi de l’utilisation pour connaître les exigences d’accès et le schéma de la table d’utilisation.

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 l'ID de client Claude Code default ci-dessous, ou configurez votre propre application OAuth. Pour ajouter un MCP avec l'ID client default, exécutez :

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

Remplacez le hostname, l’ID de workspace et le nom de MCP. Ouvrez Claude Code, entrez /mcp et 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>?o=<workspace-id>"

  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.

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.

  • 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