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). Neither surface sends anything to us: the MCP server talks over stdio, and the CLI reads your metadata on this machine. What leaves is metadata only, and only when you run one of four commands — invite, watch, push, start; the last three only once this machine is paired, and invite shows you exactly what goes before 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 portal, 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 from Regixo. A table named patients_oncology is confidential. regixo mcp sends nothing to the network — it answers over a stdio pipe. What your agent then does with what it read is your agent's business: if it runs on a hosted model, your schema reaches that provider.
• 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.

Procedure A · Register the read-only server

Registration is a one-time setup with a clear shape: print the config (or copy it from the portal) → paste it into your client → hand the agent the reading playbook → restart and ask → confirm it reads. Every step is below, and the exact paste location differs only by client.

Step 1 — print the config

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.

Steps 1–2, without the terminal — connect from the portal

If the command line is not where you work, you do not have to touch it to connect — this does Steps 1 and 2 in the browser instead. Once the portal 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",
        "REGIXO_CONFIG": "/Users/you/app/regixo.yml"
      }
    }
  }
}

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 --env REGIXO_CONFIG=/abs/regixo.yml -- 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.

Step 2 — paste it into your client (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.

Step 3 — hand the agent the reading playbook

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.

Step 4 & 5 — restart, then confirm it reads

Restart the app so it launches the server, then ask it a question about your data — you should see it call Regixo's tools before it answers. That is the confirmation: a real tool call, not a guess. What a session looks like, below, shows the exact call order for four questions; if the assistant answers those without calling a tool, the registration didn't take — re-check the paste location for your client in Step 2.

The eight read tools

Every tool is a read. The set is fixed — the agent sees exactly these, and no others. One is conditional in the portal only: the Agents screen lists get_dora when DORA scope is declared, so on a project that has not, it lists seven. The tool itself is always registered — off scope it answers {inScope:false}.

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

Worked examples, shown as static text: the tool-call order, and what comes back — in plain words, not the raw JSON. Three of these four are the playbook's own examples. We do not put words in your assistant's mouth; we do not know which words it will choose. What we do know is the data Regixo hands it, so that is what is described here:

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

What those calls return, in plain words:
  two matches — app-db/public/users.email and
  marketing.contacts.email, both flagged Email (personal data)
  provenance: one source (stripe) not scanned since 12 Jun,
  so the map is 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

What that call returns, in plain words:
  stamp: DRAFT — not an official record
  12 activities: 9 with every legal field confirmed by a person,
  3 still showing purpose or lawful basis as suggested
  a suggestion is Regixo's guess — only the compliance team can confirm it

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       datasetId:"app-db/public/payments"

What that call returns, in plain words:
  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 are not 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

What that call returns, in plain words:
  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, attributed to the person who did it

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.

Procedure B · Drive the CLI with 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.

Step 1 — hand it the playbook (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.

AGENTS.md is a convention, not a standard. It is the file most coding agents read first, and Regixo writes there — but not every tool reads it. Cursor reads .cursor/rules, Copilot .github/copilot-instructions.md, Gemini GEMINI.md. If yours reads a different file, point that file here; Regixo will not do it for you, and says so when it writes.

$ regixo help --json

Step 2 — say the task; it runs the 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.

Step 3 — check the result, not the agent's summary

An agent's account of its own work is not evidence. Check what Regixo says: regixo status ends on the coverage line — ✓ all source(s) reached, or the bad case that names the missing source — with the dataset and personal-data counts beside it to compare against your estate. A record it drafted stays DRAFT; anything it wrote lands suggested until a person confirms it. These are the same four signals the human half of this contract walks in full: Work with your agent → the four signals.

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).

How you know each procedure worked

• Procedure A (register the MCP server) — after a restart, your assistant calls a Regixo tool before it answers (you can see the call), and its answer matches the map. If it answers a question about your data with no tool call, the server isn't registered — re-check the paste location in Step 2.
• Procedure B (drive the CLI) — the change you asked for shows up where Regixo reports it: a new source on the coverage line, a corrected flag in regixo classify list, a forwarded draft in regixo status. You read it from Regixo's own output, never from the agent's summary.

Both leave the trust story intact: the MCP surface is read-only by construction, and an agent driving the CLI reads names and types only. The scan stays on your machine; four commands upload, and only when they are run: invite, watch, push, start — the last three only once this machine is paired — and invite shows a person what would go before anything moves.