Canonic MCP server

canonic

<!-- mcp-name: io.github.mischuh/canonic -->

The context layer that lets AI agents query your data correctly.

Point canonic at your database and it builds the context an agent needs to answer data questions accurately: definitions, relationships, business meaning, and the guardrails that stop confidently-wrong answers. It keeps that context up to date as your data changes, and it never touches your warehouse beyond reading it.

📖 Full documentation: https://docs.getcanonic.app

Package and image names below show the shape of each install channel; exact names are confirmed per release.

The problem

An AI agent connected straight to your warehouse sees tables and columns, not meaning. It doesn't know that revenue lives in orders.amount but excludes refunds, or that "active customer" has a specific definition your finance team agreed on. So it guesses. Schema access makes an agent fluent. It doesn't make it correct.

Real output, captured from a live run against the ecommerce example:

$ canonic sql "SELECT SUM(amount) FROM fct_orders"
┏━━━━━━━━━┓
┃ sum     ┃
┡━━━━━━━━━┩
│ 4050.50 │
└─────────┘

This total includes two refunded orders ($260), a confident, well-formatted number that's off by 6.4%.

$ canonic --json query --metrics revenue
{
  "result": { "rows": [["3790.50"]] },
  "compiled": {
    "sql": "SELECT SUM(\"orders\".\"amount\") AS \"total_revenue\" FROM \"fct_orders\" AS \"orders\" WHERE \"orders\".\"status\" <> 'refunded'"
  },
  "metadata": {
    "guardrails_fired": [{ "id": "revenue-excludes-refunds", "kind": "mandatory_filter" }]
  }
}

canonic resolves "revenue" to its canonical definition, compiles the guardrail into the SQL whether or not anyone asked for it, and returns the right number with the reasoning attached.

canonic is not a BI tool and not a chat interface: it's the layer that feeds the tools you already have (a BI dashboard, an agent, a notebook) correct, governed answers.

The three layers

canonic's context lives in three committed surfaces: plain files in your git repo, reviewed like code.

Changes how the SQL runs → semantics. A human needs it to trust the answer → knowledge. Governs which definition is authoritative → contracts. See Concepts: the three layers.

Install

uv (dev machines, primary):

uvx canonic --version        # ephemeral, no install step
uv tool install canonic      # persistent, global command

pip (fallback for environments without uv):

pip install canonic

Docker (CI, headless, air-gapped):

docker pull ghcr.io/mischuh/canonic:latest

Verify with canonic --version. Air-gapped install and offline wheels: see Installation.

Quickstart

The fastest path uses local connectors, no server, no network. Point at a SQLite .db or DuckDB .duckdb/CSV/Parquet file:

canonic setup

Shortened. The full README is on GitHub.