Databricks SQL

Important

This feature is in Public Preview.

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. Use it to build data pipelines from AI coding tools. Queries run asynchronously: the agent calls the tool to start a query, then polls until the response completes.

URL pattern OAuth scope
https://<workspace-hostname>/api/2.0/mcp/sql sql

_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 for executing 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 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())
  • Last updated on