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

Um system.ai.sandbox, system.ai.web_search oder system.ai.dbsql zu verwenden, muss ein Kontoadministrator die Unity Gateway-Beta über die Seite Previews der Kontokonsole aktivieren. Siehe Kontovorschauen verwalten.

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 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 Databricks SQL MCP-Server, 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.

Verbinden Sie Ihren Agenten

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 Agenten, SELECT 1 AS result auszuführen. Bestätigen Sie, dass es das MCP-Tool aufruft und 1 zurückgibt.

_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 für die Ausführung von Abfragen verwendet werden soll.
Beispiel: "a1b2c3d4e5f67890"
Wenn nicht angegeben, wählt das System automatisch ein Lager basierend auf Ressourcen und Berechtigungen aus.

Beispiel: Angeben eines SQL-Warehouses für SQL-Abfragen für Databricks

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 für die Abfrageausführung, anstatt dem System die automatische Auswahl zu ermöglichen.
  • Ü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:

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
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())

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. Der Agent startet zunächst eine Abfrage und fragt anschließend wiederholt den Status ab, bis diese abgeschlossen ist; daher muss er Zwischenzustände berücksichtigen.

Legacy-Arbeitsbereich-Endpunkt

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.

  • Zuletzt aktualisiert um