Obi & MCP

Obi is the conversational agent built into ObeliskDB — your guide to the monolith. Ask it to query data, build objects, manage grants, run pipes, or explain a result, in plain language. Everything Obi does flows through the same governed session as a human, so RBAC, masking, budgets, and history apply to it identically. External agents reach the same engine over MCP.

Talking to Obi

Obi lives in the control plane (chat is the primary surface) and in a chat widget on every app page. It runs a tool loop: it can look up the catalog, describe tables, query metrics, search insights, run SQL, and read the docs — then answer with the actual result.

Two ground rules shape its behavior:

• - It answers analytics questions through governed metrics when one fits, falling back to SQL otherwise.
• - It confirms genuinely destructive operations before running them — and, in an agent session, the engine refuses the irreversible ones outright regardless of what Obi decides. See The guarantees.

Every Obi reply carries a session line: statements run, credits spent against budget, and the branch when a change was staged.

Backends

Obi auto-detects its model, with no configuration required:

• - Anthropic API — set ANTHROPIC_API_KEY (or use an ant profile). The quality option; reliable multi-step tool use.
• - Local Ollama — no API key, fully offline. Install Ollama, ollama pull qwen3:4b, and Obi finds it on localhost:11434. Small local models are weaker at multi-step orchestration — great for lookups and queries, more hand-holding on complex builds.

MCP: external agents

obelisk mcp runs a Model Context Protocol server (stdio) so any MCP-capable client — a coding agent, another LLM — can use ObeliskDB through one session. Register it, for example:

claude mcp add obelisk -- uv run --directory ~/obeliskdb obelisk mcp

The tools mirror Obi's: run_sql, list_objects, describe_table, list_metrics, query_metric, find_insights, verified_sql, context_pack, query_history, docs, pipes, and model builds.

The important part: an external agent connected this way inherits every guarantee without knowing they exist. Its writes stage on a branch, its spend is budgeted, its statements are logged, and irreversible operations are refused — because the contract is enforced beneath it, not implemented in it.

Governed MCP

Set OBELISK_MCP_GOVERNED=1 to hand an external agent a session restricted to metrics and insights only. Raw table reads, DML, and DDL are refused in the executor, and the agent cannot opt out. Use it when you want a coding agent to ask your data questions but never touch raw tables. See compelled governance.

Context packs

context_pack returns one token-budgeted briefing of the platform — catalog with row counts, metrics, insights and their freshness, warehouses, session context — so an agent starts informed instead of groping through SHOW TABLES. Also available at GET /api/context/pack.