Databricks SQL MCP server

The Databricks SQL MCP server lets agents run AI-generated SQL against your Unity Catalog tables to read and write data, with access governed by Unity Catalog permissions. Queries run asynchronously: the agent calls the tool to start a query, then polls until the response completes.

Important

system.ai.dbsql, system.ai.sandbox, and system.ai.web_search are in Beta. To use them, an account admin must enable the Enhanced Unity Gateway preview from the account console Previews page. Unity Gateway itself is generally available. See Manage account previews.

If the beta isn't enabled, calls to system.ai.dbsql return The MCP service is administratively suspended. (HTTP 400). Use the workspace endpoint /api/2.0/mcp/sql instead.

Use this server for development and data engineering: running a specific query you or your coding agent wrote, inspecting schemas, validating SQL syntax, and authoring data pipelines from AI coding tools. It gives you deterministic control over the exact SQL that runs.

The MCP permits reads and writes by default. To make it read-only, set disallow_writes to true in the built-in system.ai.dbsql_policy policy. See Apply a policy.

Genie One MCP versus Databricks SQL MCP servers

For business questions asked in natural language, Databricks recommends the Genie One MCP server. Genie resolves business terms through Genie Ontology, your governed semantic layer. This produces more accurate answers than an agent writing SQL directly against raw tables.

Use the Databricks SQL MCP server when you need to run a specific query you or your coding agent wrote, such as validating syntax or authoring a pipeline.

To ask questions scoped to a single curated Genie Agent, use the Genie Agent MCP server. For a comparison of all three servers, see Choose between Genie One, Genie Agent, and Databricks SQL MCP servers.

Connect your agent

Use this URL with your coding agent's setup guide or Python agent setup:

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

Ask your agent to run SELECT 1 AS result. Confirm that it calls the MCP tool and returns 1.

Tools

The Databricks SQL MCP server provides the following tools:

Tool Arguments Description
execute_sql query Runs a SQL statement, including statements that write data. Writes are blocked if disallow_writes is true in the server policy.
execute_sql_read_only query Runs a read-only SQL statement, such as SELECT, SHOW, or DESCRIBE.
poll_sql_result statement_id Returns the current state and results of a statement that execute_sql or execute_sql_read_only started.

Each tool returns JSON text that includes statement_id and status.state. When the state is SUCCEEDED, the rows are in result.data_typed_array.

_meta parameters

_meta parameters are configuration values that you preset in your agent code to set the MCP server's behavior deterministically, rather than letting the LLM generate them dynamically at tool-call time. The Databricks SQL MCP server supports the following _meta parameter:

Parameter name Type Description
warehouse_id str The ID of the SQL warehouse to use to run queries.
Example: "a1b2c3d4e5f67890"
If not specified, the system automatically selects a warehouse based on resources and permissions.

Example: specify a SQL warehouse for Databricks SQL queries

This example shows how to use the warehouse_id _meta parameter to specify which SQL warehouse runs queries from the Databricks SQL MCP server using the official Python MCP SDK.

In this scenario, you want to:

  • Use a specific SQL warehouse to run queries instead of letting the system select one automatically
  • Verify consistent performance by routing queries to a dedicated warehouse

To run this example, set up your Python environment for managed MCP development:

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

To find your SQL warehouse ID, see Connect to a SQL warehouse.

# 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 and CANCELED are terminal states, so the example stops polling and raises an error.

Limitations

  • No semantic context. The server runs the SQL it's given. It doesn't resolve business terms, metric definitions, or table relationships, so an agent must infer them from schemas alone. For analytics questions asked in natural language, use the Genie One MCP server, which grounds answers in Genie Ontology.
  • Result size. The server truncates large result sets in tool responses to avoid exhausting the model's context window. Return fewer rows and columns, or aggregate in SQL, to keep results within the limit.
  • Asynchronous execution. Queries don't return synchronously. A query that's still running returns the state PENDING or RUNNING and a statement_id. Call poll_sql_result with that ID until the state changes. See Example: specify a SQL warehouse.

Workspace endpoint

This endpoint is in Public Preview.

For existing integrations, use https://<workspace-hostname>/api/2.0/mcp/sql with the sql OAuth scope. This endpoint uses the Managed MCP Servers workspace preview and underlying resource permissions. Calls bypass Unity Gateway tracing, MCP grants, policies, and guardrails. For new integrations, use system.ai.dbsql.