Connetti gli MCP agli assistenti di intelligenza artificiale e agli agenti di codifica

Connettere client, assistenti di intelligenza artificiale e IDE che supportano il protocollo MCP (Model Context Protocol) a Databricks MCP. In questo modo è possibile accedere ai dati e agli strumenti di Databricks direttamente nell'ambiente di sviluppo.

Collegando i client agli MCP di Databricks, è possibile:

• Accedere a funzioni, tabelle e indici vettoriali di Unity dall'IDE o dall'assistente di intelligenza artificiale
• Eseguire interrogazioni sui dati di Databricks direttamente da Claude, Claude Code, Cursor, Replit o altri strumenti con supporto MCP

Come funziona

Ogni client si connette agli MCP di Databricks nello stesso modo: basta aggiungere l'URL del server alla configurazione MCP del client, autenticarsi con OAuth o un token di accesso personale e il client richiama gli strumenti tramite HTTP streamable. L'URL determina quale MCP raggiungi: un server MCP gestito per i dati e gli strumenti del Catalogo Unity, un servizio MCP per strumenti esterni o il tuo server MCP ospitato su Databricks:

Requisiti

• URL del server: ottenere gli URL del server appropriati per il server MCP di Databricks che si vuole usare:
  • server MCP gestiti per i dati e il codice di Azure Databricks
  • Servizi MCP per app di terze parti come Slack, GitHub e Google Drive
  • Server MCP ospitati da Databricks per il proprio server MCP in Databricks Apps
• Accesso alle risorse: verificare di avere accesso ai server MCP da usare e alle risorse sottostanti. Ad esempio, se si usa il server MCP gestito genie, è necessario accedere all'agente Genie sottostante.
• Accesso alla rete: se l'area di lavoro di Databricks ha restrizioni di accesso IP, aggiungere gli indirizzi IP in uscita del client all'elenco consenti di abilitarlo per connettersi all'area di lavoro:
  • Seguire la documentazione relativa agli elenchi di accesso IP dell'area di lavoro e agli elenchi di accesso IP dell'account per verificare se sono presenti restrizioni
  • Se gli elenchi di accesso IP sono abilitati, identificare gli indirizzi IP in uscita del client. Queste informazioni sono in genere disponibili nella documentazione client; Ad esempio, Claude documenta gli indirizzi IP in uscita qui.
  • Assicurarsi che gli indirizzi IP in uscita del client vengano aggiunti all'elenco.

Metodi di autenticazione

Scegliere il metodo di autenticazione più adatto ai requisiti di sicurezza:

Connettere i client usando l'autenticazione OAuth

OAuth fornisce l'autenticazione sicura con autorizzazioni con ambito e aggiornamento automatico dei token.

Ottenere l'URL di reindirizzamento OAuth del client

Ogni client MCP richiede URL di reindirizzamento OAuth specifici per i callback di autenticazione. I modelli comuni di URL di reindirizzamento includono:

• Client basati sul Web: https://<domain>/oauth/callback o https://<domain>/api/mcp/auth_callback
• Strumenti di sviluppo locali: http://localhost:<port>/oauth/callback

Controllare la documentazione del client per trovare gli URL di reindirizzamento esatti necessari.

Creare l'applicazione OAuth di Databricks

Chiedere a un amministratore dell'account di creare un'applicazione OAuth di Databricks. Recuperare l'ID client e, se il client lo richiede, il segreto client.

Basato sull'Interfaccia Utente (Console Account)

Creare un'applicazione OAuth di Databricks usando la console dell'account:

1. Nella console dell'account Databricks passare a Impostazioni>Connessioni> appAggiungi connessione.
2. Configurare le impostazioni dell'applicazione:
   • Nome: immettere un nome descrittivo per l'applicazione OAuth ( ad esempio claude-mcp-client, mcp-inspector)
   • URL di reindirizzamento: aggiungere gli URL di reindirizzamento richiesti dal cliente esterno
   • Tipo di client: Per i client pubblici (browser, dispositivi mobili), deselezionare Genera un segreto del client. Per i client riservati (lato server), mantenerli controllati.
   • Ambiti: configurare gli ambiti dell'API (vedere le informazioni di riferimento per gli ambiti OAuth di Databricks per gli ambiti disponibili)
   • Scadenza del token: impostare i tempi di accesso e aggiornamento del token appropriati

CLI

Creare un'applicazione OAuth di Databricks usando l'interfaccia della riga di comando di Databricks.

databricks account custom-app-integration create --json '{
  "name": "mcp-oauth-client",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["all-apis"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

databricks account custom-app-integration create --json '{
  "name": "mcp-public-oauth-app",
  "redirect_urls": ["https://<your-client-redirect-url>"],
  "confidential": false,
  "scopes": ["genie", "unity-catalog", "offline_access"],
  "token_access_policy": {
    "access_token_ttl_in_minutes": 60,
    "refresh_token_ttl_in_minutes": 10080
  }
}'

{
  "client_id": "<your-client-id>",
  "client_secret": "",
  "integration_id": "<your-integration-id>"
}

Configurare l'accesso alla rete (facoltativo)

Se l'area di lavoro di Databricks ha restrizioni di accesso IP, aggiungere gli indirizzi IP in uscita del client all'elenco elementi consentiti dell'area di lavoro. In caso contrario, l'area di lavoro blocca le richieste di autenticazione dal client. Vedere Gestire gli elenchi di accesso IP.

Configurare il client

Dopo aver creato l'applicazione OAuth in Databricks, configurare il client MCP specifico con le credenziali OAuth. Ogni client ha un proprio metodo di configurazione. Vedere gli esempi specifici della piattaforma seguenti per istruzioni dettagliate per i client MCP più diffusi.

Esempi di OAuth

Gli esempi seguenti illustrano come configurare client MCP specifici con l'autenticazione OAuth. Seguire prima i passaggi di installazione generici di OAuth nella sezione precedente, quindi usare questi esempi per configurare il client specifico.

Controllo MCP

MCP Inspector è uno strumento di sviluppo per il test e il debug dei server MCP.

Seguire la configurazione dell'autenticazione OAuth precedente con queste impostazioni specifiche di Inspector:

• URL di reindirizzamento:
  • http://localhost:6274/oauth/callback
  • http://localhost:6274/oauth/callback/debug
• Tipo di client: Pubblico ( deselezionare Genera un segreto client)

Configurare l'Ispettore MCP:

1. Eseguire il controllo: npx @modelcontextprotocol/inspector.
2. Impostare Tipo di trasporto su Streamable HTTP.
3. Immettere l'URL del server MCP di Databricks.
4. Nella sezione Autenticazione aggiungere l'ID client OAuth.
5. Fare clic su Apri impostazioni di autenticazione e scegliere Flusso guidato o rapido .
6. Dopo aver completato l'autenticazione, incollare il token di accesso in Bearer Token nella sezione API Token Authentication.
7. Fare clic su Connetti.

Connettori Claude

Connettere Claude ai server MCP gestiti da Databricks e ai servizi MCP usando Claude Connectors con McP remoto.

Seguire la configurazione dell'autenticazione OAuth precedente con queste impostazioni specifiche di Claude:

• URL di reindirizzamento: https://claude.ai/api/mcp/auth_callback e https://claude.com/api/mcp/auth_callback
• Elenco indirizzi IP consentiti (se necessario): aggiungere gli indirizzi IP in uscita di Claude

Configurare Claude:

1. Passare a Impostazioni >Connettori in Claude.
2. Fare clic su Aggiungi connettore personalizzato.
3. Immettere l'URL del server MCP di Databricks.
4. Immettere l'ID client dell'applicazione OAuth e il segreto client se la connessione all'app OAuth di Databricks è un client riservato.
5. Fare clic su Aggiungi per terminare.

Claude Code

Il modo più rapido per connettere Claude Code avviene con ucode, che si autentica tramite l’accesso alla CLI di Databricks, senza bisogno di un’applicazione OAuth, di un ID client o di un client secret:

uv tool install git+https://github.com/databricks/ucode
ucode mcp add --agents claude --services <catalog>.<schema>.<service>
ucode claude

Sostituisci <catalog>.<schema>.<service> con il nome completamente qualificato del Servizio MCP. Vedi Integra con gli agenti di codifica per i dettagli.

OpenAI Codex

Collega OpenAI Codex ai server Databricks MCP con ucode, che si autentica tramite il login della CLI Databricks—nessuna applicazione OAuth, client ID o client secret necessari:

uv tool install git+https://github.com/databricks/ucode
ucode mcp add --agents codex --services <catalog>.<schema>.<service>
ucode codex

Sostituisci <catalog>.<schema>.<service> con il nome completamente qualificato del Servizio MCP. ucode scrive il server MCP nella configurazione del Codex e aggiorna automaticamente il token OAuth. Vedi Integra con gli agenti di codifica per i dettagli.

App ChatGPT

Connettere ChatGPT ai server MCP gestiti di Databricks e ai servizi MCP usando app ChatGPT personalizzate con la modalità sviluppatore e le app MCP complete.

L'aggiunta di app ChatGPT personalizzate richiede:

• Modalità sviluppatore attivata
• Un'area di lavoro ChatGPT Business, Enterprise o Edu

Seguire la configurazione dell'autenticazione OAuth precedente con queste impostazioni specifiche di ChatGPT:

• URL di reindirizzamento: https://chatgpt.com/connector_platform_oauth_redirect
• Elenco indirizzi IP consentiti: aggiungere gli indirizzi IP in uscita di ChatGPT

Configurare ChatGPT:

1. In ChatGPT passare a Impostazioni>App>crea app.
2. Immettere l'URL del server MCP di Databricks.
3. Usare OAuth come metodo di autenticazione.
4. Immettere l'ID client e il segreto dell'applicazione OAuth (se applicabile).
5. Completare la configurazione e salvare l'app.

Cursore/Windsurf

Per connettere un IDE locale, ad esempio Cursor o Wind, a un server MCP di Databricks, aggiungere il server MCP al file di configurazione MCP.

1. Individuare il file di configurazione MCP:

   • Cursore: ~/.cursor/mcp.json
   • Windsurf: ~/.codeium/windsurf/mcp_config.json

2. Aggiungere una delle configurazioni seguenti. Per Cursor, ucode è l'opzione più semplice. In caso contrario, usare l'opzione OAuth corrispondente al tipo di client.

uv tool install git+https://github.com/databricks/ucode
ucode mcp add --agents cursor --services <catalog>.<schema>.<service>
ucode cursor

{
  "mcpServers": {
    "databricks-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
        "--static-oauth-client-info",
        "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\", \"client_secret\": \"$MCP_REMOTE_CLIENT_SECRET\" }"
      ]
    }
  }
}

{
  "mcpServers": {
    "databricks-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://<your-workspace-hostname>/api/2.0/mcp/functions/system/ai",
        "--static-oauth-client-info",
        "{ \"client_id\": \"$MCP_REMOTE_CLIENT_ID\" }"
      ]
    }
  }
}

Connettere i client usando l'autenticazione tramite token di accesso personale

I token di accesso personale forniscono un metodo di autenticazione più semplice adatto per singoli processi di sviluppo, test e accesso a breve termine ai server MCP di Databricks.

Per i Servizi MCP, genera un token di accesso personale e passalo come token portatore nell'intestazione Authorization .

Usare questo token per i test locali e scegliere la durata più breve adatta al flusso di lavoro. Non inserire i token nel sistema di controllo del codice sorgente e non condividerli nei file di configurazione del client. Per connessioni client in produzione o estese all’intero team, usa OAuth invece di un token di accesso personale (PAT). Per gli agenti di codifica (Claude Code, Cursor, OpenAI Codex e altri), ucode è l'opzione più semplice: si autentica tramite il login della CLI Databricks e aggiorna automaticamente il token.

1. Generare un token di accesso personale nell'area di lavoro di Databricks. Vedere Autenticazione con i token di accesso personale di Azure Databricks (legacy).

2. Configurare l'accesso alla rete (facoltativo).

   Se l'area di lavoro di Databricks ha restrizioni di accesso IP, aggiungere gli indirizzi IP in uscita del client all'elenco consenti. Consultare la documentazione del client o la configurazione di rete dell'ambiente di distribuzione per ottenere gli indirizzi IP necessari.

3. Configurare il client.

   Dopo aver generato il PAT, configurare il client MCP per usarlo per l'autenticazione. Ogni client ha un proprio metodo di configurazione. Vedere gli esempi specifici della piattaforma seguenti per istruzioni dettagliate per i client MCP più diffusi.

   Quando un cliente richiede header personalizzati, passare il token come bearer token nell'header Authorization: Authorization: Bearer <YOUR_TOKEN>.

Esempi di PAT

Gli esempi seguenti illustrano come configurare client MCP specifici con l'autenticazione con token di accesso personale. Seguire prima di tutto la configurazione dell'autenticazione PAT, quindi usare questi esempi per configurare il client specifico.

Cursor

Il cursore supporta MCP tramite la configurazione delle impostazioni.

1. Aprire le impostazioni del cursore.

2. Aggiungere la configurazione seguente (adattare l'URL per il server MCP scelto):

   {
     "mcpServers": {
       "uc-function-mcp": {
         "type": "streamable-http",
         "url": "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
         "headers": {
           "Authorization": "Bearer <YOUR_TOKEN>"
         },
         "note": "Databricks UC function"
       }
     }
   }
   

3. Sostituire <your-workspace-hostname> con il nome host dell'area di lavoro databricks.

4. Sostituire <YOUR_TOKEN> con il token di accesso personale.

Claude Desktop

Claude Desktop può connettersi ai server MCP di Databricks usando mcp-remote.

1. Trova il tuo file claude_desktop_config.json:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json

2. Aggiungere la configurazione seguente (adattare l'URL per il server MCP scelto):

   {
     "mcpServers": {
       "uc-function-mcp": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "https://<your-workspace-hostname>/api/2.0/mcp/functions/{catalog_name}/{schema_name}",
           "--header",
           "Authorization: Bearer <YOUR_TOKEN>"
         ]
       }
     }
   }
   

3. Sostituire <your-workspace-hostname> con il nome host dell'area di lavoro databricks.

4. Sostituire <YOUR_TOKEN> con il token di accesso personale.

5. Riavviare Claude Desktop per rendere effettive le modifiche.

Replit

Replit supporta la connessione ai server MCP di Databricks tramite la configurazione personalizzata del server MCP.

1. Nell'area di lavoro Replit fare clic su Aggiungi server MCP.

2. Immettere l'URL del server MCP di Databricks, ad esempio:

   https://<your-workspace-hostname>/api/2.0/mcp/genie/{genie_space_id}
   

3. Aggiungere un'intestazione personalizzata:

   • Chiave: Authorization
   • Valore: Bearer <YOUR_TOKEN>

Vedere la documentazione di Replit MCP.

Risolvere problemi di connessione

Seguire questa procedura di risoluzione dei problemi per diagnosticare e risolvere i problemi di connessione comuni.

Convalidare l'autenticazione

Verificare che le credenziali di autenticazione siano configurate correttamente prima di testare la connessione.

OAuth utente-macchina (U2M)

Per l'autenticazione da utente a computer (U2M) OAuth, testare la connessione con MCP Inspector. Il flusso OAuth convalida le credenziali durante il processo di connessione.

Entità servizio (M2M)

Per l'autenticazione del principale del servizio con OAuth da macchina a macchina (M2M), testare le credenziali usando il Databricks CLI.

DATABRICKS_CLIENT_ID=<your-client-id> DATABRICKS_CLIENT_SECRET=<your-client-secret> databricks auth describe

Questo comando convalida la configurazione del principal del servizio e visualizza le informazioni sull'identità autenticata. Se il comando restituisce un errore, esaminare l'installazione dell'entità servizio e assicurarsi:

• Il principale del servizio è stato creato nel tuo account Databricks
• L'ID client e il segreto client sono configurati correttamente
• Il principale del servizio dispone delle autorizzazioni appropriate per accedere alle risorse necessarie

Verificare la configurazione di rete

Le restrizioni di rete possono impedire ai client esterni di connettersi all'area di lavoro di Databricks. Assicurarsi che tutti i criteri dell'elenco di accesso IP di Databricks siano configurati per consentire al client di connettersi all'account e all'area di lavoro di Databricks. Vedere Requisiti.

Identificare i problemi di connessione specifici del client

Provare a connettersi con un client MCP diverso per verificare se il problema persiste. Databricks consiglia di eseguire test con il controllo MCP. Se la connessione funziona con il controllo MCP ma non riesce con il client, è probabile che il problema si verifichi con la configurazione del client. Per ulteriore supporto, contattare il fornitore del cliente.

Segnalare problemi al supporto di Databricks

Se si continuano a riscontrare problemi di connessione dopo aver completato questi passaggi per la risoluzione dei problemi:

1. Esaminare i log dal client MCP, ad esempio Claude, Cursor o MCP Inspector, per individuare i messaggi di errore e le tracce dello stack.

2. Raccogliere le informazioni di diagnostica seguenti:

   • Metodo di autenticazione usato (OAuth o PAT)
   • URL del server MCP
   • Messaggi di errore dal client
   • Dettagli della configurazione di rete (restrizioni IP, regole del firewall)

3. Contattare il supporto tecnico e condividere le informazioni di diagnostica per risolvere il problema.

Limitazioni

• Registrazione client dinamica: Databricks non supporta flussi OAuth di registrazione client dinamica per server MCP gestiti, MCP Services o server MCP ospitati da Databricks. I client esterni e gli IDE che impongono la registrazione dinamica del client non sono supportati tramite l'autenticazione OAuth.
• Supporto dei token di accesso personale per i server MCP ospitati da Databricks: i server MCP ospitati in Databricks Apps non supportano i token di accesso personali per l'autenticazione.

Risorse aggiuntive

• Usare server MCP gestiti per connettere gli agenti ai dati di Unity Catalog
• Connettere gli agenti a strumenti di terze parti con i servizi MCP per accedere a servizi di terze parti
• Ospitare un server MCP personalizzato per strumenti specifici dell'organizzazione
• Competenze degli agenti per gli assistenti IA per la codifica per insegnare agli agenti di codifica come Claude Code e Cursor i modelli di sviluppo di Azure Databricks