Databricks SQL

The Databricks SQL MCP server is a Azure Databricks managed MCP server that 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.

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.

Genie One MCP vs. Databricks SQL MCP servers

For analytics use cases, where a user asks a business question in natural language, use the Genie One MCP server instead. Genie resolves business terms through Genie Ontology, your governed semantic layer, so it 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 already wrote, such as validating syntax or authoring a pipeline.

_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:

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 for query execution 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:

To find your SQL warehouse ID, see Connect to a 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>/api/2.0/mcp/sql"

    # 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

• 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. The agent starts a query, then polls until it completes, so it must handle in-progress states.