Hosting

Databricks-hosted workspace service

Transport

Streamable HTTP

Endpoint

https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql

Authentication

Databricks OAuth; scope ai-gateway. A user or service principal needs permission to invoke the MCP and access the relevant SQL warehouse and Unity Catalog data.

Requirements

• Databricks workspace and account with Unity Gateway beta enabled by an account admin.
• Workspace hostname copied from the workspace URL.
• Appropriate Unity Catalog and SQL warehouse permissions.
• MCP client supporting remote Streamable HTTP and Databricks OAuth.

Setup steps

1. Ask a Databricks account admin to enable Unity Gateway beta in the account console Previews page.
2. Copy the workspace hostname from the workspace URL (hostname only, without scheme or path).
3. Configure the endpoint https://<workspace-hostname>/ai-gateway/mcp-services/system.ai.dbsql with OAuth scope ai-gateway in a supported coding-agent client.
4. Sign in to Databricks and grant the user permission to invoke this service and access the SQL warehouse and catalog objects.
5. For a harmless connection check, execute the documented query SELECT 1 AS result.
6. The service permits writes by default; an administrator can set disallow_writes=true in system.ai.dbsql_policy to block writes.

The official page documents execute_sql and its query argument, but does not provide a complete tools/list inventory. Queries execute asynchronously. A warehouse_id may be supplied as _meta; otherwise the service selects a warehouse based on permissions and available resources.

• execute_sql

  Runs the supplied SQL against Unity Catalog data; official example uses query and documents asynchronous execution.

  Parameters: query
  01

This server’s available tools can vary by account, permissions, or configuration. The list shown is not its full runtime catalog.

• Writes are permitted by default unless an administrator sets disallow_writes=true in the built-in policy.
• No semantic layer is supplied; use Genie for business terminology and governed semantic questions.
• Large query results are truncated.
• Query execution is asynchronous.
• The SQL tool can read and write by default; Unity Catalog permissions govern access. Unity Gateway beta is required for system.ai tools.

• official product documentation

  Lists Databricks-provided managed MCP services and workspace connection model.

• official setup and tools documentation

  Documents SQL MCP endpoint pattern, OAuth scope, execute_sql example, policy-controlled writes, beta prerequisite, test query, and limitations.

• official authentication documentation

  Explains interactive coding-agent sign-in through Unity Gateway CLI, permissions, OAuth scopes, network requirements, and custom OAuth clients.

• official publisher avatar

  Verified Databricks GitHub organization avatar downloaded, decoded, and visually reviewed; used fallback tier D.

• official tool reference

  Current official page documents execute_sql, asynchronous query completion, Unity Catalog permissions, read/write policy, and Unity Gateway beta dependencies.

Documentation checked 2026-10-28T00:00:00Z. Connection has not been runtime tested.