Collega il codice Claude

Usa Claude Code o l'app desktop Claude con modelli, strumenti MCP e competenze tramite Unity Gateway. Per Claude Code, usa la CLI Unity Gateway (ug) oppure configura manualmente la connessione. Per l'app desktop, configura la connessione nelle impostazioni dell'app.

Per collegare gli strumenti a una configurazione esistente di Claude Code, vai su Aggiungi strumenti MCP. Per Claude sul web o in una sessione desktop usando il tuo account Claude, usa i connettori Claude.

Prerequisites

Hai bisogno dell'URL dello spazio di lavoro di Azure Databricks e dell'accesso ai modelli che vuoi usare. Per la configurazione desktop, installa l'ultima app desktop Claude e chiedi al tuo amministratore account un ID client OAuth, come descritto di seguito.

Se il tuo amministratore ha già configurato il tuo dispositivo, segui le istruzioni di accesso e avvio della tua organizzazione.

Claude Code

Usa la CLI Unity Gateway (consigliata)

Installa ug, poi esegui questo comando dalla cartella del progetto:

ug claude

Segui le istruzioni per selezionare il tuo spazio di lavoro e accedi. ug configura la connessione e apre il Claude Code nel tuo terminale. Inizia a lavorare con gli stessi prompt e comandi che già usi. Per cambiare modello, inserisci /model.

Continua ad aggiungere strumenti MCP per collegare dati e servizi. Per scaricare le abilità condivise, esegui ug skills add e seleziona quelle che desideri. Vedi Aggiungi strumenti e competenze per altre opzioni.

Configura manualmente il codice Claude

Unisci le seguenti impostazioni in ~/.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"
  }
}

Sostituisci <workspace-hostname> con il nome host del tuo spazio di lavoro, senza https://. Imposta <model-api-name> sul nome completo in Unity Catalog di un'API del modello Claude a cui puoi accedere e fornisci il tuo token di accesso personale di Azure Databricks.

Esegui claude dal tuo elenco di progetti. Per altre impostazioni, vedi Claude Code settings.

Aggiungi strumenti MCP

Per utilizzare system.ai.dbsql, system.ai.sandbox, o system.ai.web_search, un amministratore dell'account deve abilitare la beta Unity Gateway dalla pagina delle anteprime della console account. Vedi Gestisci anteprime dell'account.

Apri gli MCP Unity Gateway > nel tuo spazio di lavoro. Scegli un MCP integrato o registra il tuo server MCP esterno.
Copia il nome completo del MCP, come system.ai.github o <catalog>.<schema>.<service>.
Conferma di avere accesso all'MCP.
Dopo l'installazione ug, aggiungi l'MCP a Claude Code:
```
ug mcp add --agents claude --names <catalog>.<schema>.<service>
```
Sostituisci il segnaposto con il nome che hai copiato. Ad esempio, usa --names system.ai.github per GitHub. Per scegliere i servizi in modo interattivo, ometti --names.

Alla prima configurazione, segui le istruzioni per selezionare il tuo spazio di lavoro, accedi e scegli un modello. ug configura sia l'accesso al modello che all'MCP e aggiorna le credenziali. Riavvia Claude Code con ug claude, poi prova uno strumento.

Aggiungi manualmente gli strumenti MCP

Usa il client OAuth integrato qui sotto, oppure configura la tua app OAuth personalizzata. Per aggiungere un MCP con il client integrato, esegui:

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

Sostituisci il nome host e il nome MCP. Questo utilizza il client OAuth integrato claude-code . Apri Claude Code, inserisci /mcp, e accedi al server con il tuo account Azure Databricks. Ripeti con un nome di server diverso per ogni MCP che vuoi aggiungere, poi testa un tool.

Usa la tua app OAuth

Fai aprire a un amministratore Impostazioni > Connessioni app > Aggiungi connessione nella console account.
Inserisci un nome come claude-code-mcp, deseleziona Genera un segreto client per un client pubblico, imposta l'URL di reindirizzamento su http://localhost:8080/callback, e seleziona l'ambito ai-gateway. Salva e copia l'ID Client. Vedi Crea un'app OAuth.

Registra l'MCP usando quell'ID client e la porta di callback corrispondente:

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

Apri Claude Code, inserisci /mcp, e accedi. Se la tua organizzazione richiede un client confidenziale, aggiungi --client-secret al comando e inserisci il segreto quando richiesto.

Testa uno strumento MCP

In Claude Code, inserisci /mcp e verifica che il server sia connesso.
Chiedi a Claude di elencare gli strumenti di quel server, poi richiedi un'operazione di lettura. Per GitHub, chiedigli di trovare un problema in un repository a cui puoi accedere. Per un server personalizzato, usa uno strumento e gli input che hai testato durante la registrazione.
Se una chiamata tramite strumento ti chiede di accedere, apri il link di accesso restituito dall'MCP, completa il consenso del fornitore, poi riprova la chiamata.
Controlla che Claude effettui una chiamata allo strumento e restituisca il risultato. Una sola risposta testuale non verifica la connessione.

Per utilizzare Azure Databricks data, connettiti system.ai.genie_one_mcp per domande aziendali o system.ai.dbsql per SQL. Ad esempio, chiedi al SQL MCP di eseguire SELECT 1 AS result.

Per permessi, politiche e utilizzo, vedi Governare un MCP.

Collega manualmente le competenze

Per esporre le competenze pubblicate di Unity Gateway come strumenti, registra il registro delle abilità come server 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>"

Sostituisci i segnaposto con il tuo spazio di lavoro, il token e lo schema delle competenze. Mantieni la barra finale prima di ?schema. Per includere più schemi, ripeti il parametro: ?schema=main.default&schema=ml.prod.

Riavvia Claude Code e controlla la connessione con /mcp. Chiedi a Claude di usare un'abilità con il suo nome completo, come Use <catalog>.<schema>.<skill-name> to review this query. questa connessione espone competenze come strumenti MCP; ug skills add scarica invece competenze per la scoperta nativa.

Application desktop Claude

1. Ottenere un ID client OAuth

Chiedi al tuo amministratore di account di creare una connessione OAuth per le applicazioni. Nella console account Azure Databricks, apri Impostazioni > connessioni > App Aggiungi connessione e utilizza:

Setting	Value
Tipo di identità	Applicazione standard
Nome applicazione	`claude-desktop`
Generare un segreto del client	Deselezionato (cliente pubblico)
URL di reindirizzamento	`http://127.0.0.1:53180/callback`
Ambiti di accesso	`ai-gateway`

Salva la connessione e copia l'ID Client. Se intendi collegare le competenze, registrati anche http://127.0.0.1:53280/callback.

2. Connettiti al Gateway Unity

Dalla schermata di accesso dell'app desktop, seleziona Aiuto > Risoluzione > dei problemi Abilita la modalità sviluppatore, poi Sviluppatore > Configura inferenza di terze parti.

Nella pagina Connessione , seleziona Gateway e inserisci:

Setting	Value
Tipo di credenziali	Accesso interattivo
URL di base del gateway	`https://<workspace-hostname>/ai-gateway/anthropic`
ID del cliente	Il tuo ID client OAuth
URL dell’emittente	`https://<workspace-hostname>/oidc`
Token del portatore	Token di accesso
Ambiti	`ai-gateway`
Aggiungi `offline_access`	Attivata
Porta di reindirizzamento	`53180`

Sostituisci <workspace-hostname> con il tuo nome host di Azure Databricks workspace. Lascia le altre impostazioni alle impostazioni predefinite. Vedi la configurazione del gateway di Anthropic per i dettagli sul campo.

Clicca su Test connessione e accedi ad Azure Databricks. Seleziona Applica modifiche, poi Salva e Riavvia. Nella schermata di accesso, scegli la configurazione di terze parti e avvia una conversazione in Code o Cowork.

3. Aggiungere strumenti e competenze MCP

Apri Developer > Configura i connettori di inferenza > di terze parti. In Managed MCP servers, aggiungi una voce per ogni MCP o registro di abilità che vuoi usare.

Usa queste impostazioni per entrambi i tipi di connettore:

Setting	Value
Transport	HTTP gestibile in streaming
OAuth	Porta il tuo cliente
ID del cliente	Il tuo ID client OAuth
Segreto del cliente	Lasciare vuoto
Server di autorizzazione	`["https://<workspace-hostname>/oidc"]`
Scope	`ai-gateway`
Richiesta `offline_access`	Attivata
Conduttore di callback	`127.0.0.1`

Per un MCP, trova il suo nome in tre parti sotto Unity Gateway > MCPs nel tuo spazio di lavoro. Assegna al connettore un nome descrittivo, imposta la porta Callback su 53180, e usa questo URL:

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

Per le competenze, assegna un nome al connettore databricks-skill-registry, imposta Porta di callback su 53280 e usa:

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

Mantieni la barra finale prima di ?schema. Per includere più schemi, ripeti il parametro: ?schema=main.default&schema=ml.prod. Queste competenze vengono esposte a Claude come strumenti tramite il connettore.

Per ogni connettore, clicca su Accedi e testa e completa l'accesso. Seleziona Applica modifiche, poi Salva e Riavvia. Chiedi a Claude di usare uno strumento connesso o un'abilità con il nome completo. Vedi Aggiungi strumenti e competenze per i requisiti di accesso e altre opzioni.

Connettori Claude

Per system.ai.dbsql, prima abilita la beta di Unity Gateway.

Usa un connettore personalizzato per aggiungere gli strumenti Azure Databricks MCP a Claude sul web o desktop usando il tuo account Claude.

Fai creare un client OAuth da un amministratore dell'account. Per un MCP, seleziona l'ambito ai-gateway e registra entrambi gli URL di reindirizzamento:
- https://claude.ai/api/mcp/auth_callback
- https://claude.com/api/mcp/auth_callback
In Claude, apri Impostazioni > Connettori > Aggiungi connettore personalizzato.

Inserisci l'URL MCP:

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

Inserisci l'ID client OAuth e, per un client confidenziale, il suo segreto. Clicca su Aggiungi e completa l'accesso.
Durante una conversazione, abilita il connettore e chiedi a Claude di chiamare uno dei suoi strumenti. Per system.ai.dbsql, prova SELECT 1 AS result.

Se il tuo spazio di lavoro limita gli IP in arrivo, consenti gli IP in uscita di Claude. Vedi autenticazione MCP, rete e connettività per permessi, accesso provider e risoluzione dei problemi.

Usa un token di accesso personale nel desktop Claude per i test locali

Questa opzione richiede Node.js con npx e un token di accesso personale. Funziona per MCP forniti e registrati da Databricks, e per endpoint di workspace legacy. I server ospitati su Databricks Apps richiedono OAuth.

Unisci questa voce a claude_desktop_config.json in ~/Library/Application Support/Claude/claude_desktop_config.json su macOS o %APPDATA%\Claude\claude_desktop_config.json su Windows:

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

Sostituisci i segnaposto, tieni i token fuori dal controllo del codice sorgente e riavvia Claude desktop. Chiedi a Claude di chiamare uno strumento di sola lettura per verificare la connessione.

Troubleshooting

Il codice Claude non si collega: Esegui ug doctor se usi ug. Per la configurazione manuale, controlla il nome host dello spazio di lavoro, il token, il nome del modello e i permessi del modello.
Fallimento del login desktop: Controlla l'ID client, /oidc l'emittente e ai-gateway l'ambito di copertura. L'URL di reindirizzamento registrato deve corrispondere all'host e alla porta del connettore: 53180 per modelli e MCP, oppure 53280 per le skill presenti in questa guida. Le modifiche all'applicazione di OAuth possono richiedere fino a 30 minuti per entrare in vigore.
Manca un modello desktop: Controlla i permessi del modello. Nella lista Modelli di Connessione >>, aggiungi il nome completo del Catalogo Unity del modello. Una lista esplicita sostituisce la scoperta automatica, quindi includi tutti i modelli che vuoi usare. Applica le modifiche e ricomincia da capo.
Un MCP o un connettore di competenze non funziona: Verifica l'URL e le autorizzazioni. Il campo server di autorizzazione deve contenere l'array JSON mostrato sopra. Clicca su Accedi e testa per controllare l'errore.
L'accesso Workspace funziona, ma uno strumento ti chiede di effettuare il login: Apri il link di accesso restituito dall'MCP, accedi al provider esterno, poi riprova la chiamata. L'accesso allo spazio di lavoro e il login del fornitore sono passaggi separati.
Claude Code OAuth segnala un disallineamento di reindirizzamento o la connessione scade: Per un'app OAuth personalizzata, abbina il suo URL di reindirizzamento all'host e alla porta di callback, e controlla l'accesso alla rete. Le modifiche all'app OAuth possono impiegare fino a 30 minuti per avere effetto.

Passaggi successivi

Commenti e suggerimenti

Questa pagina è stata utile?

Ultimo aggiornamento: 2026-10-08