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.
Components
| Component | Responsibility |
|---|---|
| Transport | Carries MCP over stdio, or over Streamable HTTP with loopback and token protections |
| MCP surface | The five tools and the resources. Every tool call is recorded as an execution |
| Statement lifecycle | Builds each statement, applies the read-only check, submits it, waits, cancels and shapes the bounded result |
| Export manager | Submits an export, downloads its chunks from the presigned links and writes the files |
| Metadata queries | Catalogs, schemas, tables and columns through the Unity Catalog API, and search through information_schema |
| Metadata cache | Keeps describe_table and list_objects answers in cache.db, so a fresh entry needs no request |
| Warehouse selection | Chooses the warehouse: explicit, configured, or the remembered automatic choice |
| Authentication | Resolves the credentials and keeps the token fresh; tokens never leave memory |
| Log store | Queues 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
fetchagainst 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
dakunless 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.