Skip to content

Architecture ​

dak is one package with one binary. It runs as an MCP server on your machine, either over stdio for one session or as a shared Streamable HTTP server. It has no backend of its own: it calls the public Databricks REST APIs with the identity you configure, and it keeps its logs, a cache of metadata answers and its exports on local disk.

How dak connects a coding agent to Databricks

Components ​

Inside the dak process, the MCP surface feeds the statement lifecycle, the metadata queries and the log store; the metadata queries go through the metadata cache, which keeps its answers in cache.db and calls the Databricks REST APIs with the token on a miss; the lifecycle also calls them with the token, the export manager downloads chunks from cloud storage without it and writes the export directory, and the log store writes logs.db

ComponentResponsibility
TransportCarries MCP over stdio, or over Streamable HTTP with loopback and token protections
MCP surfaceThe five tools and the resources. Every tool call is recorded as an execution
Statement lifecycleBuilds each statement, applies the read-only check, submits it, waits, cancels and shapes the bounded result
Export managerSubmits an export, downloads its chunks from the presigned links and writes the files
Metadata queriesCatalogs, schemas, tables and columns through the Unity Catalog API, and search through information_schema
Metadata cacheKeeps describe_table and list_objects answers in cache.db, so a fresh entry needs no request
Warehouse selectionChooses the warehouse: explicit, configured, or the remembered automatic choice
AuthenticationResolves the credentials and keeps the token fresh; tokens never leave memory
Log storeQueues log events and writes them to SQLite in batches

Sequence of an export ​

An export is the longest path through the server, because the rows go from Databricks to a file without passing through the agent.

Design principles ​

  • Read-only by default. Writes need an explicit switch. The check is defense in depth; the identity's privileges are the boundary. See read-only mode.
  • A small tool surface. Five tools keep the definitions short, so they cost little context in every session. See ADR 0006.
  • REST only, no Databricks SDK. The server uses fetch against public REST APIs, which keeps the dependency list short. See ADR 0001.
  • Exports stay on the server machine. Rows never travel through the agent's context, and the files never leave the machine that runs dak unless you move them. See exporting results.
  • stdout belongs to the protocol. In stdio mode the server writes nothing to stdout except MCP messages. Diagnostics go to the log store or to stderr.

Decisions and details ​

The rest of the design, with the modules, the logging policy and the delivery pipeline, is in the design document. Each decision that shaped the system has an ADR.

Released under the MIT License.