Claude Code verbinden

Verwenden Sie Claude Code mit Modellen, MCP-Tools und Fähigkeiten über Unity Gateway. Verwenden Sie die Unity Gateway CLI (ug) zur Konfiguration des Zugriffs oder konfigurieren Sie die Verbindung manuell.

Verwenden Sie Claude Code mit unterstützten Open-Source-Modellen über Unity Gateway, um die Kosten für Codieragenten zu senken.

Um Tools mit einem bestehenden Claude Code-Setup zu verbinden, gehe zu Add MCP tools.

Prerequisites

Du brauchst die URL deines Azure Databricks Workspaces, Zugriff auf die Modelle, die du verwenden möchtest, und den neuesten Claude Code.

Wenn Ihr Administrator Ihr Gerät bereits konfiguriert hat, folgen Sie den Anweisungen Ihrer Organisation zur Anmeldung und zum Start.

Installiere und führe ugdann diesen Befehl aus deinem Projektverzeichnis aus:

ug claude

Folgen Sie den Anweisungen, um Ihren Arbeitsbereich auszuwählen und sich anzumelden. ug konfiguriert die Verbindung und öffnet Claude Code in deinem Terminal. Fang an, mit denselben Eingabeaufforderungen und Befehlen zu arbeiten, die du bereits benutzt. Um die Modelle zu ändern, geben Sie /model ein.

Fahren Sie fort, MCP-Tools hinzuzufügen, um Daten und Dienste zu verbinden. Um freigegebene Skills herunterzuladen, starte ug skills add und wähle die gewünschten Skills aus. Weitere Optionen finden Sie unter Tools und Fähigkeiten hinzufügen.

Bringen Sie Ihr eigenes Claude-Abonnement mit

Um Claude Code auf Ihrem eigenen Claude Pro-, Max-, Enterprise- oder Team-Abonnement über Unity Gateway auszuführen, bitten Sie Ihren Administrator um einen Claude Max/Enterprise Model Provider Service. Siehe Claude Max und Anthropic Enterprise Support für Anforderungen, Admin-Setup, Funktionsweise und Einschränkungen.

Übergeben Sie den vollqualifizierten Namen des Modellanbieter-Dienstes (<catalog>.<schema>.<name>) an --provider und die Arbeitsbereich-URL an --workspace:

ug claude --provider main.default.claude_subscription --workspace https://<workspace>.databricks.com

ug konfiguriert Claude Code so, dass er den Databricks-Model-Provider-Service Header sendet und Claude Code auf einen lokalen Aktualisierungsproxy verweist, anstatt direkt auf den Unity Gateway-Endpunkt. Der Proxy leitet jede Anfrage an https://<workspace-url>/ai-gateway/anthropic weiter und fügt den Header X-Databricks-AI-Gateway-Token hinzu. Da der Dienst keine Zugangsdaten speichert, leitet ug Ihr Anthropic OAuth-Token statt eines API-Schlüssels weiter.

Wenn der Claude Code dich zur Authentifizierung auffordert, wähle Option 1 – Claude-Konto mit Abonnement und melde dich mit deinem Anthropic-Konto an. Wenn Probleme auftreten, melde dich mit claude /logout ab und dann erneut an.

Note

--provider für einen Claude Max/Enterprise-Modellanbieter-Dienst wird nur mit ug claude unterstützt.

Konfigurieren Sie ein Claude-Abonnement manuell

Benutze die manuelle Einrichtung nur, wenn du nicht ug nutzen kannst.

  1. Azure Databricks-Token abrufen. Der Header X-Databricks-AI-Gateway-Token enthält ein Azure Databricks-Token, das die Anfrage bei Unity Gateway authentifiziert. Unity Gateway ordnet Zugriffskontroll- und Nutzungsprotokolle der mit diesem Token verknüpften Identität zu, also verwenden Sie ein Token, das dem anfragenden Benutzer gehört. Wählen Sie eines der folgenden Szenarien aus:

    • OAuth Benutzer-zu-Computer (U2M) mit der Databricks CLI (empfohlen). Melde dich einmal mit der CLI an und präge dann einen kurzlebigen OAuth-Token:

      databricks auth login --host https://<workspace-url>
      databricks auth token --host https://<workspace-url> | jq -r .access_token
      

      Siehe Autorisieren des Benutzerzugriffs auf Azure Databricks mit OAuth und Authentifizierung für die Databricks-CLI. Ein U2M OAuth-Token läuft in etwa 1 Stunde ab, daher muss man ihn für interaktive Nutzung aktualisieren und die Variable erneut exportieren, wenn er abläuft. Um die Token-Aktualisierung zu automatisieren, verwenden Sie ug, das einen lokalen Proxy ausführt, der das OAuth-Token bei jeder Anfrage für Sie aktualisiert.

    • Personal Access Token (PAT) als Backup. Wenn du OAuth nicht verwenden kannst, erstelle einen PAT und verwende ihn als <databricks-token>. Ein PAT läuft nicht mit dem 1-Stunden-OAuth-Rhythmus ab, ist aber eine langlebige Qualifikation, die an Ihre Identität gebunden ist. Siehe Authentifizieren mit persönlichen Zugriffstokens von Azure Databricks (Legacy).

  2. Füge Folgendes zu deiner Shell-Konfigurationsdatei hinzu (~/.zshrc oder ~/.bashrc):

    export ANTHROPIC_BASE_URL="https://<workspace-url>/ai-gateway/anthropic"
    export ANTHROPIC_CUSTOM_HEADERS="X-Databricks-AI-Gateway-Token: Bearer <databricks-token>
    Databricks-Model-Provider-Service: <catalog>.<schema>.<name>"
    
    • Ersetzen Sie <workspace-url> durch Ihre Arbeitsbereichs-URL.
    • Ersetzen Sie <databricks-token> durch das Azure Databricks-Token aus dem vorherigen Schritt.
    • Ersetzen Sie <catalog>.<schema>.<name> durch den vollqualifizierten Namen Ihres Modellanbieterdienstes.
  3. Start Claude Code:

    claude
    
  4. Wenn du noch nicht eingeloggt bist, fordert dich Claude Code zur Authentifizierung auf. Wähle Option 1 – Claude-Konto mit Abonnement und logge dich mit deinem Anthropic-Konto an. Wenn Probleme auftreten, melde dich mit claude /logout ab und dann erneut an.

Deine Claude Code-Anfragen werden jetzt über Unity Gateway geleitet. Anfragen werden auf Ihr Anthropic-Abonnement abgerechnet, und Sie erhalten zentralen Zugriff, Routing und Nutzungssteuerung.

Auf Azure Databricks-Compute ausführen

Um Claude Code auf serverlosem Computing oder einem dedizierten Cluster ohne ug zu installieren auszuführen, verbinden Sie sich mit dem SSH-Tunnel und führen Sie claude aus. Der Agent ist für Unity Gateway vorkonfiguriert. Siehe Coding agents in einer SSH-Sitzung ausführen.

Claude Code manuell konfigurieren

Führen Sie die folgenden Einstellungen in ~/.claude/settings.json zusammen:

{
  "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"
  }
}

Ersetzen Sie <workspace-hostname> durch Ihren Workspace-Hostnamen, ohne https://. Setzen Sie <model-api-name> auf den vollständigen Unity-Katalognamen eines Modelldienstes, auf den Sie zugreifen können, der die Anthropic Messages API unterstützt. Dies kann ein Claude-Modell oder ein kompatibles Open-Source-Modell sein. Geben Sie Ihr persönliches Zugriffstoken für Azure Databricks an.

Führe claude aus deinem Projektverzeichnis aus. Für andere Einstellungen siehe Claude Code Einstellungen.

Automatikmodus

Der Auto-Modus ist ein Claude Code-Berechtigungsmodus, der routinemäßige Berechtigungsaufforderungen reduziert. Ein Sicherheitsklassifikator überprüft vorgeschlagene Werkzeugaktionen, wie Shell-Befehle oder Dateibearbeitungen, die sonst Ihre Zustimmung erfordern würden, und entscheidet, ob sie fortgesetzt werden können.

Anthropic-Modelle über Unity Gateway verwenden die nativen Auto-Modus-Prüfungen von Anthropic. Für nicht-Anthropic Foundation-Modelle, die von Azure Databricks gehostet werden und Funktionsaufrufe unterstützen, stellt Unity Gateway den Klassifikator bereit. Für die aktuell gepflegte Modellliste und die modellspezifischen Funktionen siehe Modelle, die über Databricks verfügbar sind.

Automatikmodus und Servicerichtlinien bieten ergänzende Prüfungen:

  • Der Auto-Modus-Sicherheitsklassifikator entscheidet, ob eine vorgeschlagene Werkzeugaktion basierend auf den Gesprächs- und Auto-Modus-Regeln ausgeführt werden kann.
  • Service-Richtlinien wenden die Governance-Regeln Ihrer Organisation auf Anfragen und Antworten auf das Modell, den Modellanbieter oder MCP-Dienste an, an die sie angehängt sind, einschließlich MCP-Tool-Aufrufen und Ergebnissen. Einige integrierte Service-Richtlinien verwenden ebenfalls ein Modell als Sicherheitsklassifikator, aber deren Entscheidungen betreffen die geregelte Service-Interaktion.

Die Genehmigung im automatischen Modus überschreibt keine durchgesetzte Dienstrichtlinie. Zum Beispiel kann eine Richtlinie auf einem MCP-Dienst eine menschliche Genehmigung für einen destruktiven Werkzeugaufruf erfordern, selbst wenn der Auto-Modus die Aktion erlaubt.

Claude Code bewertet explizite permissions.deny Regeln und inhaltsbezogene permissions.ask Regeln, bevor er den Klassifikator konsultiert. Eine übereinstimmende Deny-Regel blockiert die Aktion, und eine übereinstimmende Ask-Regel erfordert eine Berechtigungsaufforderung. Der Auto-Modus kann auch Aktionen basierend auf den Konversations- und Klassifikatorregeln blockieren oder wenn eine Überprüfung kein gültiges Urteil liefern kann.

Nachdem Sie Ihre Verbindung mit konfiguriert haben ug, starten Sie Claude Code im Auto-Modus:

ug claude -- --permission-mode auto

Mit einer manuellen Verbindung führen Sie claude --permission-mode auto aus. Für die ug Weiterleitung von Argumenten siehe ug CLI-Referenz.

Konfigurieren Sie die vertrauenswürdige Infrastruktur

Beschreiben Sie die vertrauenswürdigen Repositorien, Domains und Dienste Ihrer Organisation in autoMode.environment. Diese Einträge helfen dem Klassifikator, den erwarteten Zugriff auf deine Infrastruktur von Aktionen zu unterscheiden, die er blockieren sollte. Fügen Sie beispielsweise einen autoMode-Block in Ihre Benutzereinstellungen unter ~/.claude/settings.json ein, z. B.:

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

Ersetzen Sie die Beispieleinträge durch die Infrastruktur Ihrer Organisation. Die Einträge sind Beschreibungen in natürlicher Sprache. Behalten Sie "$defaults" bei, um die integrierten Umgebungseinträge zu erhalten, wenn Sie eigene hinzufügen.

Der Klassifikator liest autoMode aus Benutzereinstellungen, verwalteten Einstellungen oder der Inline---settings-Konfiguration. Dieser Block wird nicht aus dem Projekt .claude/settings.json oder .claude/settings.local.json gelesen. Administratoren können freigegebene Konfigurationen über verwaltete Einstellungen verteilen.

Für Regelanpassung, verwaltete Einstellungen und Überprüfung blockierter Aktionen siehe Automodus konfigurieren.

Verwendung von Klassifikatoren nachverfolgen

Die Unity Gateway-Prüfungen senden vorgeschlagene Toolargumente und Konversationskontext an ein separates Klassifikatormodell. Klassifikator-Anfragen verursachen zusätzliche Modellgebühren und können die Latenz erhöhen.

Klassifikatoranfragen erscheinen in system.ai_gateway.usage mit invocation_metadata.source gesetzt auf SAFEGUARD_CLASSIFIER. Verwenden Sie diesen Wert, um Sicherheitsprüfanfragen sowie deren Tokennutzung und -latenz von den Anfragen Ihres Codingmodells zu unterscheiden. Weitere Informationen zu Zugriffsanforderungen und zum Nutzungstabellenschema finden Sie unter Nutzungsnachverfolgung.

MCP-Werkzeuge hinzufügen

system.ai.dbsql, system.ai.sandbox, und system.ai.web_search befinden sich in der Beta. Um sie zu nutzen, muss ein Kontoadministrator die Vorschau des Enhanced Unity Gateway auf der Seite Previews der Kontokonsole aktivieren. Unity Gateway selbst ist jetzt verfügbar. Siehe Kontovorschauen verwalten.

  1. Öffnen Sie die Unity Gateway > MCPs in Ihrem Arbeitsbereich. Wählen Sie ein integriertes MCP oder registrieren Sie Ihren externen MCP-Server.

  2. Kopieren Sie den vollständigen Namen des MCP, wie zum Beispiel system.ai.github oder <catalog>.<schema>.<service>.

  3. Bestätigen Sie, dass Sie Zugang zum MCP haben.

  4. Nach der Installation ugfügen Sie das MCP zu Claude Code hinzu:

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

    Ersetze den Platzhalter durch den Namen, den du kopiert hast. Verwenden Sie zum Beispiel --names system.ai.github für GitHub. Um Dienste interaktiv auszuwählen, lassen Sie --names weg.

Beim ersten Einrichten folgen Sie den Anweisungen, wählen Sie Ihren Arbeitsbereich aus, melden Sie sich an und wählen Sie ein Modell aus. ug konfiguriert sowohl den Modell- als auch den MCP-Zugriff und aktualisiert die Zugangsdaten. Starte Claude Code mit ug claudeneu und teste dann ein Werkzeug.

MCP-Werkzeuge manuell hinzufügen

Verwenden Sie unten die Standard-Claude-Code-Client-ID oder konfigurieren Sie Ihre eigene OAuth-App. Um ein MCP mit der Standard-Client-ID hinzuzufügen, führen Sie aus:

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>"

Ersetzen Sie den Hostnamen, Workspace-ID und den MCP-Namen. Öffnen Sie Claude Code, geben Sie /mcp ein und melden Sie sich mit Ihrem Azure Databricks-Konto beim Server an. Wiederhole das mit einem anderen Servernamen für jedes MCP, das du hinzufügen möchtest, und teste dann ein Tool.

Benutze deine eigene OAuth-App
  1. Lass einen Kontoadministrator in der KontokonsoleEinstellungen > App-Verbindungen > Verbindung hinzufügen öffnen.

  2. Geben Sie einen Namen wie claude-code-mcp ein, deaktivieren Sie Client-Geheimnis generieren für einen öffentlichen Client, setzen Sie die Umleitungs-URL auf http://localhost:8080/callback, und wählen Sie den ai-gateway Scope aus. Speichere und kopiere die Client-ID. Siehe Eine OAuth-App erstellen.

  3. Registrieren Sie das MCP mit dieser Client-ID und dem passenden Callback-Port:

    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. Claude Code öffnen, /mcp eingeben und sich anmelden. Wenn Ihre Organisation einen vertraulichen Client benötigt, fügen Sie --client-secret dem Befehl hinzu, und geben Sie das Geheimnis ein, wenn Sie dazu aufgefordert werden.

MCP-Tool testen

  1. Im Claude Code geben Sie ein /mcp und prüfen Sie, ob der Server verbunden ist.
  2. Bitte Claude, die Tools dieses Servers aufzulisten, und fordere dann eine Leseoperation an. Für GitHub bitten Sie GitHub, ein Problem in einem Repository zu finden, auf das Sie zugreifen können. Für einen benutzerdefinierten Server verwenden Sie ein Tool und Eingaben, die Sie während der Registrierung getestet haben.
  3. Wenn Sie bei einem Tool-Aufruf zur Anmeldung aufgefordert werden, öffnen Sie den vom MCP bereitgestellten Anmeldelink, erteilen Sie die erforderliche Zustimmung beim Anbieter, und wiederholen Sie anschließend den Aufruf.
  4. Überprüfen Sie, ob Claude einen Werkzeugaufruf macht und das Ergebnis zurückgibt. Eine Textantwort allein bestätigt die Verbindung nicht.

Um Azure Databricks-Daten zu verwenden, verbinden Sie system.ai.genie_one_mcp für Geschäftsfragen oder system.ai.dbsql für SQL. Zum Beispiel kann der SQL-MCP aufgefordert werden, SELECT 1 AS result auszuführen.

Für Berechtigungen, Richtlinien und Nutzung siehe Verwalten eines MCP.

Fähigkeiten manuell verbinden

Um veröffentlichte Unity-Gateway-Skills als Werkzeuge bereitzustellen, registrieren Sie das Skill-Registry als HTTP-MCP-Server:

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>"

Ersetze die Platzhalter durch deinen Arbeitsplatz, den Token und dein Fertigkeitsschema. Behalten Sie den abschließenden Schrägstrich vor ?schema bei. Um mehrere Schemata einzubeziehen, wiederhole den Parameter: ?schema=main.default&schema=ml.prod.

Claude Code neu starten und die Verbindung mit /mcpüberprüfen. Bitte Claude, eine Fähigkeit mit ihrem vollständigen Namen zu verwenden, wie zum Beispiel Use <catalog>.<schema>.<skill-name> to review this query. Diese Verbindung offenlegt Fähigkeiten als MCP-Werkzeuge; ug skills add lädt stattdessen Fähigkeiten für native Entdeckung herunter.

Troubleshooting

  • Claude Code verbindet sich nicht: Führe ug doctor aus, wenn du ug benutzt. Für die manuelle Einrichtung überprüfen Sie Ihren Workspace-Hostnamen, Token, Modellname und Modellberechtigungen.

  • Claude Code OAuth meldet eine Redirect-Fehlanpassung oder die Verbindung läuft ab: Für eine benutzerdefinierte OAuth-App gleichen Sie deren Redirect-URL mit dem Callback-Host und Port ab und prüfen Sie den Netzwerkzugang. Änderungen der OAuth-App können bis zu 30 Minuten dauern, bis sie wirksam werden.

Nächste Schritte