Databricks connector

The Databricks connector connects to the Databricks managed SQL MCP server at https://<workspace>/api/2.0/mcp/sql and the Databricks REST API. Agents and workflows use the connector to execute SQL statements, manage jobs and clusters, control SQL warehouses, and monitor alerts. The connector also supports other Databricks MCP servers such as Genie and AI Search by changing the server URL.

You can create connectors in Stack Management > Connectors.

Databricks connectors have the following configuration properties:

MCP server URL

The Databricks SQL MCP server URL for your workspace (for example, https://<workspace>.azuredatabricks.net/api/2.0/mcp/sql). Replace <workspace> with your workspace hostname. For other MCP server types (Genie, AI Search), change the path accordingly.

Authentication

Supports two authentication methods:

• OAuth Authorization Code (recommended): Uses the Databricks workspace-level OIDC authorization code flow. Requires a Client ID, Client Secret, Authorization URL, and Token URL from a registered Databricks OAuth application. See OAuth credentials for setup instructions.
• Personal access token (PAT): A Databricks personal access token for quick testing or automated access.

The Databricks connector exposes the following actions:

runQuery

Execute a read-only SQL query against the Databricks SQL warehouse. Only SELECT, SHOW, DESCRIBE, DESC, EXPLAIN, and WITH statements are permitted — INSERT, UPDATE, DELETE, and DDL are blocked by the server (execute_sql_read_only). For long-running queries, returns a statement_id — use pollResponse to retrieve results.

• statement (required): The read-only SQL query to execute (for example, SELECT * FROM main.default.customers LIMIT 10 or SHOW TABLES IN main.default).

executeStatement

Execute a SQL statement on the Databricks SQL warehouse. Supports DML (INSERT, UPDATE, DELETE), DDL (CREATE, ALTER, DROP), SHOW, DESCRIBE, and other SQL dialects supported by Databricks SQL. Use this action only when write operations are needed — prefer runQuery for read-only statements. This action is available to workflows but is not exposed to AI agents. For long-running queries, returns a statement_id — use pollResponse to retrieve results.

• statement (required): The SQL statement to execute (for example, INSERT INTO main.default.users VALUES (1, 'Alice')).

pollResponse

Poll the status and retrieve results for a previously submitted SQL query. Use this when runQuery or executeStatement returns a statement_id instead of immediate results. Returns the query status (RUNNING, SUCCEEDED, FAILED, CANCELLED) and, when complete, the result set. Poll repeatedly until the status is SUCCEEDED or FAILED.

• statementId (required): The statement ID returned by runQuery or executeStatement (for example, 01ef1234-5678-abcd-efab-cdef01234567).

listRuns

List job runs in the workspace. Returns run metadata including state, start time, and task results. Optionally filter by job ID or active-only runs.

• jobId (optional): Filter to runs from a specific job.
• activeOnly (optional): If true, return only active runs (PENDING, RUNNING, TERMINATING).
• limit (optional): Maximum number of runs to return (default 20, max 25).
• pageToken (optional): Cursor from a previous response for pagination.

getRun

Get full details for a specific job run, including state, tasks, start/end times, and error messages.

• runId (required): The run ID to retrieve (for example, 455644833).

getRunOutput

Retrieve the output of a completed task run (notebook output, return values, logs). Requires a task-level run ID from getRun's tasks[].run_id — not the top-level run_id returned by runJobNow or listRuns. Call getRun first to find the task run IDs.

• runId (required): A task-level run ID from getRun's tasks[].run_id.

runJobNow (workflow only)

Trigger a Databricks job run immediately. Returns a run_id to track progress with getRun.

• jobId (required): The job ID to trigger.
• jobParameters (optional): Key-value pairs to override job parameters (for example, { "env": "prod" }).

cancelRun (workflow only)

Cancel an active job run. The run must be in PENDING or RUNNING state. Cancellation is asynchronous — poll getRun until state is CANCELLED.

• runId (required): The run ID to cancel.

repairRun (workflow only)

Re-run failed tasks in a completed job run without re-running tasks that succeeded. Returns a repair_id.

• runId (required): The run ID to repair.
• rerunTasks (optional): One or more task keys to re-run. Mutually exclusive with rerunAllFailedTasks.
• rerunAllFailedTasks (optional): Set to true to re-run all failed tasks. Mutually exclusive with rerunTasks. Exactly one of rerunTasks or rerunAllFailedTasks: true must be provided.
• latestRepairId (optional): ID of the most recent repair when chaining multiple repairs.

listClusters

List all clusters in the workspace. Returns cluster metadata including cluster_id, cluster_name, state (RUNNING, TERMINATED, PENDING), spark_version, and node type.

startCluster (workflow only)

Start a terminated cluster. Startup is asynchronous — poll listClusters until state is RUNNING.

• clusterId (required): The cluster ID (for example, 0923-164208-meows279).

restartCluster (workflow only)

Restart a running cluster. Restart is asynchronous — poll listClusters until state returns to RUNNING.

• clusterId (required): The cluster ID.

listWarehouses

List all SQL warehouses in the workspace. Returns warehouse metadata including id, name, state (RUNNING, STOPPED, STARTING), cluster_size, and auto_stop_mins.

startWarehouse (workflow only)

Start a stopped SQL warehouse. Startup is asynchronous — poll listWarehouses until state is RUNNING.

• warehouseId (required): The SQL warehouse ID.

stopWarehouse (workflow only)

Stop a running SQL warehouse to save costs. Stop is asynchronous — poll listWarehouses until state is STOPPED.

• warehouseId (required): The SQL warehouse ID.

listAlerts

List all SQL alerts in the workspace. Returns alert metadata including id, name, state (OK, TRIGGERED, UNKNOWN), and query_id.

getAlert

Get full details for a specific SQL alert, including the associated query, condition, notification schedule, and current state.

• alertId (required): The alert ID.

listTools (workflow-only)

List all tools available on the connected Databricks MCP server. Use this to discover server capabilities and verify exact tool names before using callTool. Different Databricks MCP servers expose different tools — the SQL server provides execute_sql, execute_sql_read_only, and poll_sql_result, while the Genie server provides query_space and poll_response.

callTool (workflow-only)

Call any tool on the Databricks MCP server directly by name. Use this as an escape hatch for tools not yet exposed as named actions, or for tools on non-SQL Databricks MCP servers such as Genie (query_space) or AI Search. Use listTools first to discover available tool names and their arguments.

• name (required): Name of the Databricks MCP tool to call (for example, execute_sql).
• arguments (optional): Arguments to pass to the tool as a key-value map.

For long-running queries, runQuery or executeStatement returns a statement_id instead of immediate results:

1. Call runQuery (for read-only SQL) or executeStatement (for DML/DDL) with your SQL statement.
2. If the response contains a statement_id, the query is still running.
3. Call pollResponse with the statement_id until the status is SUCCEEDED or FAILED.
4. Once SUCCEEDED, the response contains the full result set.

Use the Action configuration settings to customize connector networking, such as proxies, certificates, or TLS settings. You can set configurations that apply to all your connectors or use xpack.actions.customHostSettings to set per-host configurations.

The Databricks connector supports two authentication methods: OAuth Authorization Code (recommended) and Personal Access Token (PAT).

Use this method to authorize the connector using the Databricks workspace OIDC authorization code flow.

1. Log in to your Databricks workspace and go to Settings > Developer > App connections (or the equivalent for your workspace type).
2. Register a new OAuth application and set the redirect URI to https://<your-kibana-host>/api/actions/connector/_oauth_callback.
3. Note the Client ID and Client Secret for use in Kibana.
4. In Kibana, create a Databricks connector and select OAuth Authorization Code as the authentication method. Enter:
   • Authorization URL: https://<workspace>.azuredatabricks.net/oidc/v1/authorize
   • Token URL: https://<workspace>.azuredatabricks.net/oidc/v1/token
   • Client ID and Client Secret from step 3.
5. Authorize with your Databricks account to complete the OAuth flow.

Refer to the Databricks OAuth user-to-machine (U2M) documentation for detailed setup instructions.

Use this method for quick testing or automated access.

1. In your Databricks workspace, go to User Settings > Developer > Access tokens.
2. Select Generate new token, enter a description and optional lifetime, then select Generate.
3. Copy the token and store it securely.
4. In Kibana, create a Databricks connector and select Personal access token (PAT) as the authentication method. Enter the token in the Databricks access token field.