Use an AI agent

An agent works with Regixo two separate ways, and mixing them up is the easiest mistake to make. Operating Regixo — you tell the coding agent already open in your project what you want, and it runs the ordinary regixo command; nothing to install, nothing to register (that surface →). Reading the catalog — a registered, read-only assistant answers questions about your data over MCP; it changes nothing, and setting it up is a real one-time step (this page, below). Regixo sends nothing to Regixo on either surface: the MCP server talks over stdio, and the CLI reads your metadata on this machine. The one thing that ever leaves is the metadata-only snapshot regixo invite uploads — and only after it shows you exactly what leaves and you say yes. And neither surface may confirm a legal field or sign.

What regixo mcp is

One local process, launched by your AI app, talking to it over stdio — standard in and out, no network. It reuses the same reader that serves the dashboard, so the agent sees exactly what the map shows. Three properties define it:

• Local, over stdio. The agent launches regixo mcp as a child process and talks to it through a pipe. There is no port, no socket, no cloud relay.
• Zero metadata egress. A table named patients_oncology is confidential. stdio carries nothing to the network — nothing about your schema is sent anywhere.
• Read-only by construction. There is no write, set or confirm tool — not a disabled one, none at all. The server structurally cannot change your catalog or confirm a legal field.

Connect it once

Print the registration block for your AI app, then paste it into that app's MCP settings:

$ regixo mcp --print-config

It prints a JSON mcpServers block, pinned to this project's absolute paths. Copy it as-is:

{
  "mcpServers": {
    "regixo": {
      "command": "npx",
      "args": [
        "regixo",
        "mcp"
      ],
      "env": {
        "REGIXO_DATA": "/Users/you/app/.regixo",
        "REGIXO_CONFIG": "/Users/you/app/regixo.yml"
      }
    }
  }
}

Your real paths are filled in for you. REGIXO_CONFIG appears only when a regixo.yml exists next to your catalog.

Connect from the dashboard, without the terminal

If the command line is not where you work, you do not have to touch it to connect. Once the dashboard is running (regixo open), open Help ▾ → Agents (MCP). That screen does the same registration through the browser, in two numbered steps:

• Pick your client from the tabs — Claude Desktop · Claude Code · Cursor · VS Code · Other / CLI. Each tab names the exact config file and where it belongs on disk.
• Press Copy snippet to take the ready-made config — the same block --print-config prints, with your absolute paths already filled in — then paste it into that client's MCP settings.
• Claude Code gets a one-line command instead of a JSON block (shown below), so there is no file to edit.
• Copy the reading playbook — a regixo mcp --skill button beside the snippet prints the markdown skill that teaches your agent when to call which tool, and how to read the trust signals. Paste it into your agent's instructions.
• Then restart the app and ask it about your data — that is step 2, and it is the whole of the setup.
• Further down the same screen, "What your agent can read" lists all 8 read tools by name, each with what it returns — the same read-only, metadata-only set the CLI serves. They are listed below too.

The page also separates the two agent surfaces, so they don't get confused: this registration lets an assistant read the catalog; having your coding agent run Regixo needs no registration at all — it already has a terminal, and the page hands it the playbook with regixo skill.

{
  "mcpServers": {
    "regixo": {
      "command": "npx",
      "args": [
        "regixo",
        "mcp"
      ],
      "env": {
        "REGIXO_DATA": "/Users/you/app",
        "REGIXO_CONFIG": "/Users/you/app"
      }
    }
  }
}

For Claude Code the tab offers this single command to run once, rather than a config file to hand-edit:

$ claude mcp add regixo --env REGIXO_DATA=/abs/.regixo -- npx regixo mcp

This is the path to point anyone to who is not at home on the command line: pick, copy, paste. The same screen is walked through in the free portal tour.

Where it plugs in

Anything that reads an mcpServers block takes the same JSON. The registration is identical across apps — only where you paste it differs:

• Claude Desktop — Settings → Developer → Edit config, paste the block, restart.
• Claude Code — add it to your MCP config, or run the one-line claude mcp add command; the tools appear on the next launch.
• Cursor — MCP settings (.cursor/mcp.json), paste the same block.
• VS Code — .vscode/mcp.json, paste the same block.
• Other / CLI — any MCP-compatible client: point it at the stdio command regixo mcp. Same JSON shape; only the wrapper key differs.

To teach the agent when to call which tool and how to read the trust signals, print the short playbook and paste it into the agent's instructions:

$ regixo mcp --skill >> AGENTS.md

The playbook is versioned markdown: the tool-selection order, the trust vocabulary, worked examples, and Hard Rule #4 carried verbatim as an instruction. It carries no secrets, so it commits freely.

The eight read tools

Every tool is a read. The set is fixed — the agent sees exactly these, and no others:

A missing or misnamed argument comes back as a JSON-RPC error naming the exact parameter (missing required "q"), never a silent empty result. Asking get_dataset for an unknown id returns the same DATASET_NOT_FOUND body the HTTP API returns — one error shape across both surfaces.

Two surfaces, one reader

The same catalog answers on two channels, backed by one shared reader — so they never disagree. Which you use depends on the agent:

regixo mcp logs to stderr, because stdout is the protocol channel. It blocks by design — you don't run it by hand; your AI app starts and stops it.

While regixo open is running, the same reader is exposed as a versioned JSON read API on localhost:4319 — ten read-only routes, the machine equivalent of the eight MCP tools:

Every route is a read — there is no write verb on this surface either. An unknown route returns ENDPOINT_NOT_FOUND; an unknown dataset id returns the same DATASET_NOT_FOUND body get_dataset returns over MCP.

What a session looks like

These are the two worked examples from the playbook. They are shown as static text — the tool-call order and a representative answer — not a live agent:

You:   Where do we store customer email?

Agent calls, in order:
  1. search_datasets   q:"email"
  2. get_dataset       id:"app-db/public/users"
  3. get_provenance

Agent answers:
  Customer email is in app-db/public/users.email and
  marketing.contacts.email — both flagged Email (personal data).
  One source (stripe) hasn't been scanned since 12 Jun,
  so this map may be incomplete.

The third call matters: before it relies on any answer, the agent checks get_provenance, so a stale or unreachable source becomes a caveat instead of a confident wrong answer.

You:   Is our RoPA up to date?

Agent calls:
  1. get_compliance_state

Agent answers:
  This is a DRAFT, not an official record. Of 12 activities:
  9 have every legal field confirmed by a person; 3 still show
  purpose or lawful basis as suggested — those need a human on
  the compliance team to confirm before the record is complete.

The agent reports which legal fields are suggested (Regixo's guess, awaiting a human) versus confirmed (a recorded human decision) — and never presents a suggestion as settled.

You:   What feeds the payments table?

Agent calls:
  1. get_lineage       id:"app-db/public/payments"

Agent answers:
  payments is fed by app-db/public/orders and
  app-db/public/customers. One upstream is
  dbt_analytics.stg_stripe — known via dbt, not scanned,
  so its columns aren't in the map.

The agent lists only the edges Regixo actually holds. An endpoint flagged unresolvable (known via dbt — not scanned) is named as a gap, never filled in with a guess about what sits behind it.

You:   Has anything changed recently?

Agent calls:
  1. get_changes

Agent answers:
  Since the last scan on 3 Jul: two new columns in
  app-db/public/users, one dataset dropped (legacy.sessions),
  and users.internal_ref reclassified from identifier
  to not personal by a person.

The change-log is append-only, newest first, so the agent can answer "what moved" without re-reading the whole map — and it attributes a human correction to a person, never to itself.

What the MCP surface can and can't do

This is the read-only Ask side. An agent with a terminal changes the map through the CLI instead — see Do — drive Regixo from your coding agent.

The trust vocabulary the agent reads

The playbook teaches the agent to read these signals before it asserts anything. They keep it honest about how much the map can be trusted:

seal: "draft"

Nothing in a free catalog is signed or official. When the agent cites compliance state, it calls it a draft. The signed OFFICIAL record is the paid step.

suggested · confirmed

suggested is a machine guess awaiting a human; confirmed records a human decision, with who and when. Suggestions are presented as suggestions.

fresh · stale-warn · stale-loud · never

The staleness tier per source. stale-loud and never mean the map may be out of date, and the agent says so.

~N rows (estimate)

Row counts are the database's own planner estimate, never a COUNT(*). The agent presents them as estimates, never as a measured fact.

Do — operate Regixo by talking to your coding agent

Everything above is the reading surface. This is the other one: a coding agent that can run a terminal — Claude Code, Cursor's agent, a CI job — is already open in your project, so you tell it what you want and it runs the ordinary regixo command. There is nothing to install and nothing to register — no MCP server, no config file. That is the whole difference between the two surfaces, and it is why every command block in these docs shows you the sentence and the command side by side.

Every command is built to run headless: no prompts, machine-readable output, and errors that name exactly what to supply — so you don't teach the agent the commands, it reads them itself.

Set it up once

Hand the agent the playbook and it can drive the rest. regixo skill prints the whole job in order: the setup sequence, how to discover the commands, the two lines it must never cross, and where it hands back to you.

$ regixo skill

Its other reference is the manifest — the whole command line as data: every command with its usage and examples, the env vars it reads, and the full error list (code → message → fix). It reads that once and knows the surface, so it never guesses. A root AGENTS.md already points agents at it.

$ regixo help --json

Give it the right command

Ask in plain language; the agent maps it to a command. Below are the common tasks and the command the agent runs for each. A database is referenced by the name of the env var that holds its connection string — never the secret itself:

Every command here takes --json for a machine-readable result. Full detail per command: the command reference — or the agent's own regixo help <command> --json.

Author a new connector with your agent

Regixo ships a fixed set of connectors (SQL databases, Snowflake, BigQuery, Stripe, CSV, dbt). For anything else — a SaaS, or your organisation’s own internal API — a coding agent can author a live connector for you. Open your agent in the project and say “add <your tool> to Regixo”. It reads the playbook:

$ regixo connectors --skill

The playbook leads with an interview, because the source is usually private — the agent has no public knowledge of your internal API. It asks how the API authenticates and what its objects/fields are (or reads an internal OpenAPI spec / one sample response), then authors the connector:

• A generator script — a small script in regixo-connectors/ that prints your schema; Regixo runs it as a subprocess each scan (regixo connectors new <name> → regixo add script --generator … --ref …). Works for any tool with a REST API.
• No live access at all? Fall back to a one-off snapshot: regixo add manual --from schema.csv (no live updates).