Connectez Claude Code

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

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

Prerequisites

Vous avez besoin de l’URL de l’espace de travail Azure Databricks, de l’accès aux modèles que vous souhaitez utiliser, et du dernier Claude Code.

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

Utilisez l’interface de ligne de commande Unity Gateway (recommandée)

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

ug claude

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

Continuez vers Ajouter des outils MCP pour connecter des données et des services. Pour télécharger des compétences partagées, lancez ug skills add et sélectionnez celles que vous souhaitez. Consultez Ajouter des outils et des compétences pour plus d’options.

Configurez manuellement le code Claude

Fusionnez les paramètres suivants dans ~/.claude/settings.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 votre nom d’hôte d’espace de travail, sans https://. Définissez <model-api-name> sur le nom complet, dans Unity Catalog, d’un modèle Claude API auquel vous avez accès, et fournissez votre jeton d’accès personnel Azure Databricks.

Exécutez claude depuis votre annuaire de projet. Pour d’autres réglages, voir Claude Code settings.

Mode auto

Le mode automatique réduit les demandes d’autorisation de routine 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 auto-modes natives d'Anthropic. Pour les modèles de base non Anthropic hébergés par Azure Databricks qui prennent en charge l’appel de fonctions, Unity Gateway fournit le classificateur. Pour la liste de modèles maintenue et les capacités par modèle, voir Modèles disponibles via Databricks.

Claude Code évalue les règles explicites permissions.deny et les règles à permissions.ask portée de contenu avant de consulter le classificateur. 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 également bloquer des actions selon les règles de conversation et de classification, ou lorsqu’un test ne peut pas produire un verdict valide.

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

ug claude -- --permission-mode auto

Avec une connexion manuelle, exécutez claude --permission-mode auto. Pour le transfert ug d’arguments, voir la référence ug CLI.

Configurez une infrastructure de confiance

Décrivez les dépôts de confiance, domaines et services de votre organisation dans autoMode.environment. Ces entrées aident le classificateur à distinguer l’accès attendu à votre infrastructure des actions qu’il devrait bloquer. Intégrez un bloc autoMode à vos paramètres utilisateur dans ~/.claude/settings.json, par exemple :

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

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

Le classificateur lit autoMode à partir des paramètres utilisateur, des paramètres gérés ou de la configuration en ligne --settings. 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 la révision des actions bloquées, voir Configurer le mode automatique.

Suivi de l’utilisation du classifieur

Les contrôles de Unity Gateway envoient les arguments de l’outil proposé et le contexte de la conversation vers un modèle de classification distinct. Les demandes de classificateur entraînent des frais supplémentaires liés au modèle et peuvent ajouter de la latence.

Les requêtes de classificateur apparaissent dans system.ai_gateway.usage avec invocation_metadata.source défini à SAFEGUARD_CLASSIFIER. Utilisez cette valeur pour distinguer les requêtes de contrôle de sécurité ainsi que leur consommation de jetons et leur latence de celles de votre modèle de codage. Voir Suivi d’utilisation pour les exigences d’accès et le schéma de 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 Unity Gateway depuis la page Previews de la console de compte. Voir Gérer les aperçus du compte.

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

2. Copiez le nom complet du MCP, comme system.ai.github ou <catalog>.<schema>.<service>.

3. Confirmez que vous avez accès au MCP.

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

   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 espace de travail, vous connecter et choisir un modèle. ug configure à la fois l’accès au modèle et au MCP, et actualise les informations d’identification. Redémarrez Claude Code avec ug claude, puis testez un outil.

Ajouter manuellement les outils MCP

Utilisez l’identifiant client Claude Code par défaut ci-dessous, ou configurez votre propre application OAuth. Pour ajouter un MCP avec l’identifiant client par défaut, exécutez :

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 nom d’hôte, l’identifiant de l’espace de travail et le nom de MCP. Ouvrez Claude Code, entrez /mcp, et connectez-vous au serveur avec votre compte Azure Databricks. Répétez avec un nom de serveur différent pour chaque MCP que vous souhaitez ajouter, puis testez un outil.

Tester un outil MCP

1. Dans Claude Code, entrez /mcp et vérifiez que le serveur est connecté.
2. Demandez à Claude d’énumérer les outils de ce serveur, puis demandez d’effectuer une opération de lecture. Pour GitHub, demandez-lui de trouver un problème dans un dépôt auquel vous pouvez accéder. Pour un serveur personnalisé, utilisez un outil et des paramètres que vous avez testés lors de l’enregistrement.
3. Si un appel d’outil vous invite à vous connecter, ouvrez le lien de connexion envoyé par le MCP, accordez le consentement du fournisseur, puis réessayez l’appel.
4. Vérifiez que Claude effectue un appel d’outil et renvoie son résultat. Une réponse textuelle seule ne confirme pas la connexion.

Pour utiliser les données Azure Databricks, connectez-vous à system.ai.genie_one_mcp pour des questions métier ou à system.ai.dbsql pour SQL. Par exemple, demandez au MCP SQL d’exécuter SELECT 1 AS result.

Pour les permissions, les politiques et l’utilisation, voir Gouverner un MCP.

Connecter manuellement les compétences

Pour exposer les compétences publiées sur Unity Gateway comme outils, enregistrez le registre de compétences comme serveur HTTP MCP :

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 espaces réservés par les valeurs correspondant à votre espace de travail, votre jeton et votre schéma de compétence. Conservez la barre oblique finale avant ?schema. Pour inclure plusieurs schémas, répétez le paramètre : ?schema=main.default&schema=ml.prod.

Redémarrez Claude Code et vérifiez la connexion avec /mcp. Demandez à Claude d’utiliser une compétence par son nom complet, par exemple Use <catalog>.<schema>.<skill-name> to review this query. : Cette connexion expose les compétences comme des outils MCP ; ug skills add télécharge plutôt des compétences pour la découverte native.

Troubleshooting

• Le code Claude ne se connecte pas : Exécutez ug doctor si vous utilisez ug. Pour la configuration manuelle, vérifiez le nom d’hôte de votre espace de travail, le jeton, le nom du modèle et les permissions du modèle.

• Claude Code OAuth signale un désaccord de redirection ou la connexion expire : Pour une application OAuth personnalisée, associez son URL de redirection à l’hôte et au port de rappel, et vérifiez l’accès réseau. Les modifications de l’application OAuth peuvent prendre jusqu’à 30 minutes avant de prendre effet.

Étapes suivantes

• Connect Claude desktop
• Référence CLI ug
• Ajouter des outils et des compétences