Databricks SQL MCP Server

Der Databricks SQL MCP-Server ermöglicht es Agenten, KI-generiertes SQL gegen Ihre Unity-Catalog-Tabellen auszuführen, um Daten zu lesen und zu schreiben, wobei der Zugriff durch Unity Catalog-Berechtigungen geregelt ist. Abfragen laufen asynchron: Der Agent ruft das Tool auf, um eine Abfrage zu starten, und fragt dann ab, bis die Antwort abgeschlossen ist.

Important

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.

Wenn die Beta nicht aktiviert ist, geben Aufrufe an system.ai.dbsqlThe MCP service is administratively suspended. (HTTP 400) zurück. Nutze stattdessen den Workspace-Endpunkt/api/2.0/mcp/sql .

Nutzen Sie diesen Server für Entwicklung und Data Engineering: Führen Sie eine bestimmte Abfrage aus, die Sie oder Ihr Codierer geschrieben haben, inspizieren Sie Schemas, validieren Sie SQL-Syntax und erstellen Sie Datenpipelines mit KI-Codingtools. Es gibt dir deterministische Kontrolle über das genaue SQL, das ausgeführt wird.

Das MCP erlaubt standardmäßig Lesen und Schreiben. Um es schreibgeschützt zu machen, setzen Sie disallow_writes in der integrierten true-Richtlinie auf system.ai.dbsql_policy. Weitere Informationen finden Sie unter Eine Richtlinie anwenden.

Genie One MCP versus Databricks SQL MCP Server

Für Geschäftsfragen, die in natürlicher Sprache gestellt werden, empfiehlt Databricks den Genie One MCP-Server. Genie löst Geschäftsbegriffe über die Genie-Ontologie auf, Ihre verwaltete semantische Schicht. Das liefert genauere Antworten als ein Agent, der SQL direkt gegen Rohtabellen schreibt.

Nutzen Sie den MCP-Server von Databricks-SQL, wenn Sie eine bestimmte Abfrage ausführen müssen, die Sie oder Ihr Coding-Agent geschrieben haben, zum Beispiel die Syntax validieren oder eine Pipeline erstellen.

Um Fragen zu stellen, die auf einen einzelnen kuratierten Genie-Agenten zugeschnitten sind, nutzen Sie den Genie Agent MCP-Server. Für einen Vergleich aller drei Server siehe Wählen Sie zwischen Genie One, Genie Agent und Databricks SQL MCP Servern.

Agent verbinden

Verwenden Sie diese URL mit dem Setup-Guide Ihres Coding-Agenten oder der Python-Agenten-Einrichtung:

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

Bitten Sie Ihren Agent, SELECT 1 AS result auszuführen. Bestätigen Sie, dass es das MCP-Tool aufruft und 1 zurückgibt.

Tools

Der Databricks SQL MCP-Server bietet folgende Werkzeuge:

Tool Arguments Description
execute_sql query Führt eine SQL-Anweisung aus, einschließlich Anweisungen, die Daten schreiben. Schreibvorgänge werden blockiert, wenn disallow_writes in der Serverrichtlinie auf true gesetzt ist.
execute_sql_read_only query Führt eine schreibgeschützte SQL-Anweisung aus, wie SELECT, SHOW, oder DESCRIBE.
poll_sql_result statement_id Gibt den aktuellen Zustand und die Ergebnisse einer Anweisung, die execute_sql oder execute_sql_read_only gestartet hat, zurück.

Jedes Tool liefert JSON-Text, der status.state und statement_id enthält. Wenn der Zustand SUCCEEDED ist, liegen die Zeilen in result.data_typed_array.

_meta Parameter

_meta Parameter sind Konfigurationswerte, die Sie in Ihrem Agentencode voreingestellt haben, um das Verhalten des MCP-Servers deterministisch festzulegen, anstatt das LLM sie dynamisch zur Tool-Call-Zeit generieren zu lassen. Der Databricks SQL MCP-Server unterstützt folgenden _meta Parameter:

Parametername Typ Description
warehouse_id str Die ID des SQL-Warehouses, das zum Ausführen von Abfragen verwendet werden soll.
Beispiel: "a1b2c3d4e5f67890"
Wenn nicht angegeben, wählt das System automatisch ein Lager basierend auf Ressourcen und Berechtigungen aus.

Beispiel: Spezifizieren Sie ein SQL-Warehouse für Databricks-SQL-Abfragen

In diesem Beispiel wird gezeigt, wie sie mithilfe des warehouse_id_meta Parameters angeben können, welche SQL-Warehouse Abfragen vom SQL MCP-Server von Databricks mithilfe des offiziellen Python MCP SDK ausführt.

In diesem Szenario möchten Sie:

  • Verwenden Sie ein bestimmtes SQL-Warehouse, um Abfragen auszuführen, anstatt das System automatisch eines auswählen zu lassen
  • Überprüfen der konsistenten Leistung durch Weiterleiten von Abfragen an ein dediziertes Lager

Um dieses Beispiel auszuführen, richten Sie Ihre Python-Umgebung für die verwaltete MCP-Entwicklung ein:

pip install --upgrade databricks-mcp databricks-sdk "mcp>=1.24,<2"

Informationen zum Auffinden Ihrer SQL-Lagerhaus-ID finden Sie unter Herstellen einer Verbindung mit einem SQL-Lagerhaus.

# Import required libraries for MCP client and Databricks authentication
import asyncio
import json
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 parse the JSON text in the response
            response = await session.send_request(request, CallToolResult)
            result = json.loads(response.content[0].text)

            # Poll until the statement leaves the PENDING or RUNNING state
            while result["status"]["state"] in ("PENDING", "RUNNING"):
                await asyncio.sleep(1)
                poll_request = CallToolRequest(
                    method="tools/call",
                    params={
                        "name": "poll_sql_result",
                        "arguments": {"statement_id": result["statement_id"]},
                    }
                )
                response = await session.send_request(poll_request, CallToolResult)
                result = json.loads(response.content[0].text)

            if result["status"]["state"] != "SUCCEEDED":
                raise RuntimeError(f"Query ended in state {result['status']['state']}: {result}")

            # The rows are in result.data_typed_array
            return result["result"]["data_typed_array"]

# Execute the async function and get the rows
rows = asyncio.run(run_dbsql_tool_call_with_meta())
print(rows)

FAILED und CANCELED sind terminale Zustände, sodass das Beispiel die Abfrage stoppt und einen Fehler hervorruft.

Einschränkungen

  • Kein semantischer Kontext. Der Server führt die ihm gegebene SQL aus. Sie löst keine Geschäftsbegriffe, Metrikdefinitionen oder Tabellenbeziehungen auf, sodass ein Agent diese allein aus Schemata ableiten muss. Für analytische Fragen in natürlicher Sprache verwenden Sie den Genie One MCP-Server, der Antworten in Genie-Ontologie verankert.
  • Ergebnisgröße. Der Server verkürzt große Ergebnismengen in Tool-Antworten, um das Kontextfenster des Modells nicht zu erschöpfen. Geben Sie weniger Zeilen und Spalten zurück oder aggregieren Sie in SQL, um die Ergebnisse innerhalb der Grenze zu halten.
  • Asynchrone Ausführung. Anfragen werden nicht synchron zurückgegeben. Eine noch laufende Abfrage liefert den Zustand PENDING oder RUNNING und ein statement_id. Rufe poll_sql_result mit dieser ID auf, bis sich der Status ändert. Siehe Beispiel: Angeben eines SQL-Warehouse.

Workspace-Endpunkt

Dieser Endpunkt befindet sich in der öffentlichen Vorschauversion.

Für bestehende Integrationen verwenden Sie https://<workspace-hostname>/api/2.0/mcp/sql mit dem sql OAuth-Scope. Dieser Endpunkt verwendet die Managed MCP Servers Workspace-Vorschau und die zugrundeliegenden Ressourcenberechtigungen. Anrufe umgehen Unity Gateway Tracing, MCP-Berechtigungen, Richtlinien und Schutzmechanismen. Für neue Integrationen verwenden Sie system.ai.dbsql.