Databricks SQL MCP server

De Databricks SQL MCP-server laat agenten AI-gegenereerde SQL uitvoeren op je Unity Catalog-tabellen om data te lezen en te schrijven, met toegang die wordt beheerd door Unity Catalog-permissies. Queries worden asynchroon uitgevoerd: de agent roept de tool aan om een query te starten, en pollt vervolgens totdat het antwoord voltooid is.

Important

Om system.ai.sandbox, system.ai.web_search of system.ai.dbsql te gebruiken, moet een accountbeheerder de Unity Gateway beta inschakelen via de pagina Previews van de accountconsole. Zie Voorbeelden van accounts beheren.

Gebruik deze server voor ontwikkeling en data engineering: het uitvoeren van een specifieke query die jij of je codeeragent heeft geschreven, het inspecteren van schema's, het valideren van SQL-syntaxis en het maken van datapijplijnen vanuit AI-coderingstools. Het geeft je deterministische controle over de exacte SQL die draait.

De MCP staat standaard lezen en schrijven toe. Om dit alleen-lezen te maken, stel je disallow_writes in op true in het ingebouwde system.ai.dbsql_policy-beleid. Zie Pas een beleid toe.

Genie One MCP versus Databricks SQL MCP-servers

Voor zakelijke vragen die in natuurlijke taal worden gesteld, raadt Databricks de Genie One MCP-server aan. Genie lost zakelijke termen op via Genie Ontology, jouw beheerde semantische laag. Dit levert nauwkeurigere antwoorden op dan een agent die rechtstreeks SQL op ruwe tabellen schrijft.

Gebruik de Databricks SQL MCP-server wanneer je een specifieke query moet uitvoeren die jij of je codeeragent hebben geschreven, zoals het valideren van syntaxis of het schrijven van een pipeline.

Verbind uw agent

Gebruik deze URL met de setup-gids van je coding agent of de Python agent setup:

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

Vraag je agent om SELECT 1 AS result uit te voeren. Bevestig dat het het MCP-gereedschap aanroept en 1 retourneert.

_meta Parameters

_meta parameters zijn configuratiewaarden die je vooraf in je agentcode instelt om het gedrag van de MCP-server deterministisch in te stellen, in plaats van dat de LLM ze dynamisch genereert tijdens het aanroepen van de tool. De Databricks SQL MCP-server ondersteunt de volgende _meta parameter:

Parameternaam Type Description
warehouse_id str De id van het SQL-warehouse dat moet worden gebruikt voor het uitvoeren van query's.
Voorbeeld:"a1b2c3d4e5f67890"
Als dit niet is opgegeven, selecteert het systeem automatisch een magazijn op basis van resources en machtigingen.

Voorbeeld: een SQL-warehouse opgeven voor Databricks SQL-query's

In dit voorbeeld ziet u hoe u de warehouse_id_meta parameter gebruikt om op te geven welke SQL Warehouse query's uitvoert vanaf de Databricks SQL MCP-server met behulp van de officiële Python MCP SDK.

In dit scenario wilt u het volgende doen:

  • Gebruik een specifiek SQL Warehouse voor het uitvoeren van query's in plaats van dat het systeem er automatisch een kan selecteren
  • Consistente prestaties controleren door query's door te routeren naar een toegewezen magazijn

Als u dit voorbeeld wilt uitvoeren, stelt u uw Python-omgeving in voor beheerde MCP-ontwikkeling:

Zie Verbinding maken met een SQL-warehouse om uw SQL-warehouse-id te vinden.

# 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

  • Geen semantische context. De server draait de SQL die hij krijgt. Het lost geen zakelijke termen, metriekdefinities of tabelrelaties op, dus een agent moet ze alleen uit schema's afleiden. Voor analytische vragen die in natuurlijke taal worden gesteld, gebruik de Genie One MCP-server, die antwoorden onderbouwt in Genie Ontology.
  • Resultaatgrootte. De server kortst grote resultatensets af in tool-antwoorden om te voorkomen dat het contextvenster van het model wordt uitgeput. Geef minder rijen en kolommen terug, of aggregeer in SQL, om de resultaten binnen de limiet te houden.
  • Asynchrone uitvoering. Queries worden niet synchroon teruggegeven. De agent initieert een query en controleert vervolgens periodiek of deze is voltooid, dus hij moet tussenliggende statussen kunnen afhandelen.

Eindpunt voor verouderde werkruimte

Voor bestaande integraties, gebruik https://<workspace-hostname>/api/2.0/mcp/sql met de sql OAuth-scope. Dit endpoint gebruikt de Managed MCP Servers workspace-preview en onderliggende resource-permissies.

  • Laatst bijgewerkt om