Claude Code verbinden

Verwenden Sie Claude Code oder die Claude Desktop-App mit Modellen, MCP-Tools und Fähigkeiten über Unity Gateway. Für Claude Code verwenden Sie die Unity Gateway CLI (ug) oder konfigurieren Sie die Verbindung manuell. Für die Desktop-App konfigurieren Sie die Verbindung in den App-Einstellungen.

Um Tools mit einem bestehenden Claude Code-Setup zu verbinden, gehe zu Add MCP tools. Für Claude im Web oder für eine Desktop-Sitzung mit deinem Claude-Konto nutze Claude Connectors.

Prerequisites

Du brauchst die URL deines Azure Databricks Arbeitsbereichs und Zugriff auf die Modelle, die du verwenden möchtest. Für die Einrichtung auf dem Desktop installieren Sie die neueste Claude Desktop-App und bitten Sie Ihren Account-Administrator um eine OAuth-Client-ID, wie unten beschrieben.

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

Claude Code

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.

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://. Legen Sie für <model-api-name> den vollständigen Unity Catalog-Namen einer Claude-Modell-API fest, auf die Sie zugreifen können, und geben Sie Ihr persönliches Azure Databricks-Zugriffstoken an.

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

MCP-Werkzeuge hinzufügen

Um system.ai.sandbox, system.ai.web_search oder system.ai.dbsql zu verwenden, muss ein Kontoadministrator die Unity Gateway-Beta auf der Previews-Seite in der Kontokonsole aktivieren. 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 den unten integrierten OAuth-Client oder konfigurieren Sie Ihre eigene OAuth-App. Um ein MCP mit dem integrierten Client hinzuzufügen, führen Sie aus:

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

Ersetzen Sie den Hostnamen und den MCP-Namen. Dies verwendet den integrierten claude-code OAuth-Client. Ö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>"

  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 Secret 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 bitte GitHub, ein Problem in einem Repository zu finden, auf das du zugreifen kannst. Für einen benutzerdefinierten Server verwenden Sie ein Tool und Eingaben, die Sie während der Registrierung getestet haben.
  3. Wenn ein Tool-Anruf dich zum Anmelden auffordert, öffne den vom MCP zurückgegebenen Login-Link, erteile die Zustimmung beim Anbieter und versuche dann den Anruf erneut.
  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.

Claude Desktop-App

1. Eine OAuth-Client-ID erhalten

Bitte deinen Kontoadministrator, eine OAuth-Anwendungsverbindung zu erstellen. In der Azure Databricks-Kontokonsole öffnen Sie Einstellungen > App-Verbindungen>. Verbindung hinzufügen und verwenden:

Setting Wert
Identitätstyp Standardanwendung
Anwendungsname claude-desktop
Geheimen Clientschlüssel generieren Nicht ausgewählt (öffentlicher Client)
Umleitungs-URL http://127.0.0.1:53180/callback
Zugriffsbereiche ai-gateway

Speichere die Verbindung und kopiere die Client-ID. Wenn du vorhast, Fähigkeiten zu verbinden, melde dich ebenfalls an http://127.0.0.1:53280/callback.

2. Verbinden Sie sich mit Unity Gateway

Auf dem Anmeldebildschirm der Desktop-App wählen Sie Hilfe > bei der Fehlerbehebung > Entwicklermodus aktivieren und dann Entwickler > Inferenz von Drittanbietern konfigurieren.

Auf der Verbindungsseite wählen Sie Gateway und geben Sie ein:

Setting Wert
Art von Qualifikation Interaktive Anmeldung
Basis-URL des Gateways https://<workspace-hostname>/ai-gateway/anthropic
Client-ID Ihre OAuth-Client-ID
Aussteller-URL https://<workspace-hostname>/oidc
Bearertoken Zugriffstoken
Geltungsbereiche ai-gateway
Anhängen offline_access Aktiviert
Umleitungsport 53180

Ersetzen Sie <workspace-hostname> durch den Hostnamen Ihres Azure Databricks-Arbeitsbereichs. Lass die anderen Einstellungen auf ihren Standardeinstellungen. Siehe die Gateway-Konfiguration von Anthropic für Felddetails.

Klicken Sie auf "Verbindung testen" und melden Sie sich bei Azure Databricks an. Wähle Änderungen anwenden, dann speichern und neu starten. Wählen Sie auf dem Anmeldebildschirm die Drittanbieter-Konfiguration aus und starten Sie eine Konveration in Code oder Cowork.

3. Hinzufügen von MCP-Werkzeugen und -Fähigkeiten

Öffnen Sie Developer > Konfiguration der Inferenz durch Drittanbieter >-Connectors. Unter Managed MCP-Server fügen Sie für jedes MCP oder Skill-Registry, das Sie verwenden möchten, einen Eintrag hinzu.

Verwenden Sie diese Einstellungen für beide Steckertypen:

Setting Wert
Transport Streambares HTTP
OAuth Bringen Sie Ihren eigenen Kunden mit
Client-ID Ihre OAuth-Client-ID
Geheimer Clientschlüssel Leer lassen
Autorisierungsserver ["https://<workspace-hostname>/oidc"]
Umfang ai-gateway
Anfrage offline_access Aktiviert
Rückruf-Moderator 127.0.0.1

Für ein MCP finden Sie seinen dreiteiligen Namen unter Unity Gateway > MCPs in Ihrem Arbeitsbereich. Geben Sie dem Connector einen beschreibenden Namen, setzen Sie den Callback-Port auf 53180, und verwenden Sie diese URL:

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

Für Skills benennen Sie den Konnektor databricks-skill-registry, setzen den Callback-Port auf 53280, und verwenden Sie:

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

Behalten Sie den abschließenden Schrägstrich vor ?schema bei. Um mehrere Schemata einzubeziehen, wiederhole den Parameter: ?schema=main.default&schema=ml.prod. Diese Fähigkeiten werden Claude über den Connector als Werkzeuge verfügbar gemacht.

Für jeden Connector klicken Sie auf Anmelden & Testen und schließen Sie die Anmeldung ab. Wähle Änderungen anwenden, dann speichern und neu starten. Bitte Claude, ein verbundenes Werkzeug oder eine Fähigkeit mit seinem vollständigen Namen zu verwenden. Siehe Hinzufügen von Werkzeugen und Fähigkeiten für Zugangsanforderungen und weitere Optionen.

Claude-Konnektoren

Für system.ai.dbsql, aktiviere zuerst die Unity Gateway Beta.

Verwenden Sie einen benutzerdefinierten Connector, um Azure Databricks MCP-Tools in Claude im Web oder auf dem Desktop mit Ihrem Claude-Konto hinzuzufügen.

  1. Lass einen Kontoadministrator einen OAuth-Client erstellen. Für ein MCP wählen Sie den ai-gateway Scope aus und registrieren Sie beide Redirect-URLs:

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

  2. Öffnen Sie in Claude Einstellungen > Connectors > Benutzerdefinierten Connector hinzufügen.

  3. Geben Sie die MCP-URL ein:

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

  4. Geben Sie die OAuth-Client-ID ein und bei einem vertraulichen Client dessen Secret. Klicken Sie auf Hinzufügen und schließen Sie die Anmeldung ab.

  5. Im Gespräch aktivieren Sie den Connector und bitten Sie Claude, eines seiner Tools aufzurufen. Versuchen Sie für system.ai.dbsqlSELECT 1 AS result.

Wenn dein Arbeitsbereich eingehende IPs einschränkt, erlaube Claudes ausgehende IPs. Siehe MCP-Authentifizierung und Netzwerk für Berechtigungen, Anbieter-Login und Fehlerbehebung.

Verwenden Sie einen persönlichen Zugriffstoken in Claude Desktop für lokale Tests

Diese Option erfordert Node.js mit npx und einem persönlichen Zugriffstoken. Es funktioniert für von Databricks bereitgestellte und registrierte MCPs sowie für Legacy-Workspace-Endpunkte. Server, die auf Databricks-Apps gehostet werden, benötigen OAuth.

Führen Sie diesen Eintrag in claude_desktop_config.json bei ~/Library/Application Support/Claude/claude_desktop_config.json auf macOS oder bei %APPDATA%\Claude\claude_desktop_config.json unter Windows zusammen:

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

Ersetzen Sie die Platzhalter, halten Sie Token aus der Quellcode-Kontrolle heraus und starten Sie den Claude-Desktop neu. Bitte Claude, ein schreibgeschütztes Tool aufzurufen, um die Verbindung zu verifizieren.

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.

  • Desktop-Anmeldung fehlschlägt: Überprüfen Sie die Client-ID, /oidc den Aussteller und ai-gateway den Scope. Die registrierte Weiterleitungs-URL muss mit dem Host und Port des Connectors übereinstimmen: 53180 für Modelle und MCPs oder 53280 für Fähigkeiten in diesem Leitfaden. Änderungen an OAuth-Anwendungen können bis zu 30 Minuten dauern, bis sie wirksam werden.

  • Ein Desktop-Modell fehlt: Überprüfe deine Modellberechtigungen. Unter Connection > Models > Modellliste fügen Sie den vollständigen Namen des Unity Catalogs des Modells hinzu. Eine explizite Liste ersetzt die automatische Entdeckung, daher sollten Sie alle Modelle einbeziehen, die Sie verwenden möchten. Wenden Sie die Änderungen an und starten Sie neu.

  • Ein MCP oder Skill Connector fehlschlägt: Überprüfen Sie seine URL und Berechtigungen. Das Autorisierungsserverfeld muss das oben gezeigte JSON-Array enthalten. Klicken Sie auf Anmelden und testen , um den Fehler zu überprüfen.

  • Die Anmeldung im Arbeitsbereich funktioniert, aber ein Tool bittet dich, dich anzumelden: Öffne den vom MCP zurückgegebenen Login-Link, melde dich beim externen Anbieter an und versuche den Aufruf erneut. Arbeitsbereich und Anmeldung beim Anbieter sind getrennte Schritte.

  • 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

  • Zuletzt aktualisiert um