Databricks MCP setup: SQL, workspace and permissions

Different SQL results do not necessarily mean the connection has failed. Another catalog, another schema or an updated dataset can change the answer to the same query. Prepare a small fixed test dataset first. Record which two columns and which few records you expect. This guide describes a comparison between the existing SQL editor and a documented MCP connection, giving each part of the test a clearly defined purpose.

Distinguish SQL access from other services

Databricks documents several managed MCP connections. The SQL connection is described as Public Preview and uses this URL pattern:

https://<workspace-hostname>/api/2.0/mcp/sql

Replace the placeholder with your workspace host. External clients use Streamable HTTP and the authentication configured for your organisation. Follow the vendor instructions for OAuth and any network access restrictions. SQL access differs from access to search indexes or predefined functions. The authentication guide explains the individual layers.

Record the query context

From a visible tool to a checked record

1. Run a small query on a prepared test table in the SQL editor. Select required columns explicitly and use stable ordering. Record the result and the time of the request.

2. Connect to the chosen MCP endpoint and read its tool description. Verify that the desired SQL operation is available and inspect the parameters expected by the current version.

3. Use the same catalog, schema and query. The SQL connection supports warehouse selection through warehouse_id in _meta. Check whether your client passes that setting.

4. Wait for query completion and compare values with the editor. SQL execution is asynchronous; a request still running is not an empty final result. Record discrepancies before trying again.

Check read permissions explicitly

The SQL connection is not automatically limited to reads. Review Unity Catalog privileges and the particular access path you selected. Databricks also identifies the system.ai.dbsql MCP Service with its own policy controls. Do not assume that a setting for that service applies to the managed SQL endpoint. Start with a read test and prepare any later changes in an isolated test environment.

Choose a test purpose in the database planner. The Databricks registry search separately shows available entries. The read-access guide explains how to compare an intended restriction with actual permissions.

Are all MCP connections in a workspace equivalent?

No. Choose a service for the operation you need and check its documentation. A reachable address does not establish that it accepts the SQL query you intend to run.

Why should I record the warehouse?

So a later repetition uses the same execution context. Record the selected warehouse even if the client chose it automatically at first.

Is a visible SQL tool automatically read-only?

No. Check data privileges and the controls of the particular connection. Describing your intention does not technically restrict permitted operations.

How do I recognise a final result?

Wait for the completed request. Keep intermediate states separate from a successful result with no rows or an error. This preserves the information needed to explain a discrepancy.

Documentation read on 4 October 2026. The checks above are a proposed test plan for your environment, not a report of a connection tested here.

1. Databricks: managed MCP servers
   Show retrieval command

   curl -s https://docs.databricks.com/aws/en/agents/mcp-tools/managed-mcp
2. Databricks: external client connections
   Show retrieval command

   curl -s https://docs.databricks.com/aws/en/agents/mcp-tools/connect-clients
3. Databricks: SQL MCP server
   Show retrieval command

   curl -s https://docs.databricks.com/aws/en/agents/mcp-tools/databricks-sql

All posts