Databricks SQL MCP server

Il server SQL MCP di Databricks permette agli agenti di eseguire SQL generato dall'IA sulle tabelle di Unity Catalog per leggere e scrivere dati, con accesso regolato dai permessi di Unity Catalog. Le query vengono eseguite in modo asincrono: l'agente chiama lo strumento per avviare una query, poi interroga fino al completamento della risposta.

Importante

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.

Usa questo server per lo sviluppo e l'ingegneria dei dati: eseguire una query specifica scritta da te o il tuo agente di programmazione, ispezionare gli schemi, validare la sintassi SQL e creare pipeline dati da strumenti di codifica AI. Ti offre un controllo preciso e deterministico sull'esatta istruzione SQL che viene eseguita.

L'MCP consente letture e scritture di default. Per renderlo di sola lettura, imposta disallow_writes su true nei criteri system.ai.dbsql_policy integrati. Vedi Applicare una politica.

Genie One MCP rispetto ai server MCP SQL di Databricks

Per domande aziendali poste in linguaggio naturale, Databricks consiglia il server MCP Genie One. Genie risolve i termini di business tramite Genie Ontology, il tuo livello semantico governato. Questo produce risposte più accurate rispetto a un agente che scrive SQL direttamente su tabelle grezze.

Usa il server SQL MCP di Databricks quando devi eseguire una query specifica scritta da te o dal tuo agente di programmazione, come la validazione della sintassi o la creazione di una pipeline.

Connetti il tuo agente

Usa questo URL con la guida all'installazione del tuo agente di programmazione o alla configurazione dell'agente Python:

Modello URL Ambito OAuth
https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql ai-gateway

Chiedi al tuo agente di eseguire SELECT 1 AS result. Conferma che chiama lo strumento MCP e restituisce 1.

_meta Parametri

_meta i parametri sono valori di configurazione che preimposta nel codice dell'agente per impostare il comportamento del server MCP in modo deterministico, invece di lasciare che l'LLM li generi dinamicamente al momento della chiamata dello strumento. Il server SQL MCP di Databricks supporta il seguente _meta parametro:

Nome del parametro Type Description
warehouse_id str ID del warehouse SQL da usare per l'esecuzione di query.
Esempio: "a1b2c3d4e5f67890"
Se non specificato, il sistema seleziona automaticamente un magazzino in base alle risorse e alle autorizzazioni.

Esempio: specificare un warehouse SQL per le query SQL di Databricks

Questo esempio illustra come usare il warehouse_id_meta parametro per specificare quale SQL Warehouse esegue query dal server SQL MCP di Databricks usando il Python MCP SDK ufficiale.

In questo scenario si vuole:

  • Usare un'istanza specifica di SQL Warehouse per l'esecuzione di query anziché lasciare che il sistema ne selezioni automaticamente uno
  • Verifica prestazioni costanti instradando le query a un warehouse dedicato

Per eseguire questo esempio, configurare l'ambiente Python per lo sviluppo MCP gestito:

Per trovare l'ID del tuo SQL Warehouse, vedere Connetti a un SQL Warehouse.

# Import required libraries for MCP client and Databricks authentication
import asyncio
from databricks.sdk import WorkspaceClient
from databricks_mcp.oauth_provider import DatabricksOAuthClientProvider
from mcp.client.streamable_http import streamablehttp_client
from mcp.client.session import ClientSession
from mcp.types import CallToolRequest, CallToolResult

async def run_dbsql_tool_call_with_meta():
    # Initialize Databricks workspace client for authentication
    workspace_client = WorkspaceClient()

    # Construct the MCP server URL for DBSQL
    # Replace <workspace-hostname> with your workspace hostname
    mcp_server_url = "https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql"

    # Establish connection to the MCP server with OAuth authentication
    async with streamablehttp_client(
        url=mcp_server_url,
        auth=DatabricksOAuthClientProvider(workspace_client),
    ) as (read_stream, write_stream, _):

        # Create an MCP session for making tool calls
        async with ClientSession(read_stream, write_stream) as session:
            # Initialize the session before making requests
            await session.initialize()

            # Create the tool call request with warehouse_id in _meta
            request = CallToolRequest(
                method="tools/call",
                params={
                    # Tool name for executing SQL queries
                    "name": "execute_sql",

                    # Dynamic arguments - typically provided by your AI agent
                    "arguments": {
                        "query": "SELECT * FROM my_catalog.my_schema.my_table LIMIT 10"
                    },

                    # Meta parameters - specify which warehouse to use
                    "_meta": {
                        "warehouse_id": "a1b2c3d4e5f67890"  # Your SQL warehouse ID
                    }
                }
            )

            # Send the request and get the response
            response = await session.send_request(request, CallToolResult)
            return response

# Execute the async function and get results
response = asyncio.run(run_dbsql_tool_call_with_meta())

Limitations

  • Nessun contesto semantico. Il server gestisce l'SQL che gli viene assegnato. Non risolve termini di business, definizioni di metriche o relazioni di tabelle, quindi un agente deve dedurli solo dagli schemi. Per domande di analisi poste in linguaggio naturale, usa il server MCP di Genie One, che basa le risposte in Ontologia Genie.
  • Dimensione del risultato. Il server tronca grandi insiemi di risultati nelle risposte degli strumenti per evitare di esaurire la finestra contestuale del modello. Restituisci meno righe e colonne, oppure aggrega in SQL, per mantenere i risultati entro il limite.
  • Esecuzione asincrona. Le query non restituiscono risultati sincronamente. L'agente avvia una query, poi interroga fino al completamento, quindi deve gestire gli stati in corso.

Endpoint di workspace legacy

Per le integrazioni esistenti, usa https://<workspace-hostname>/api/2.0/mcp/sql con l'ambito sql OAuth. Questo endpoint utilizza l'anteprima dello spazio di lavoro dei Managed MCP Servers e i permessi delle risorse sottostanti.

  • Ultimo aggiornamento: