MCP · Tools

Tools: data

Nine tools on the data plane — the project's own host, resolved from the project list (list_projects), or from the project card (get_project) when the list does not carry it. Three confirm in two steps under conditions. Descriptions are quoted as the agent reads them.

run_sql#

Run ONE SQLite statement against the project's database. Accepts a deliberately narrow grammar (SELECT / INSERT / UPDATE / DELETE / CREATE TABLE / ALTER TABLE / DROP TABLE), column types TEXT|INTEGER|REAL|BOOLEAN|JSON. This is SQLite, not Postgres — no SERIAL, jsonb, timestamptz, now(). Destructive statements (DROP, unqualified DELETE/UPDATE) answer 428 with a confirmation_token and require human elevation.

Calls POST /v1/projects/:pid/sql. The grammar, the 40-condition ceilings and the guard rails are in SQL. A destructive statement — one that does not name its target with an equality on id — requires the elevation token and then a confirmation; without the token the API answers 401 and issues nothing.

apply_migration#

Apply a schema change (DDL). Alias of run_sql for CREATE/ALTER/DROP TABLE statements — same narrow SQLite grammar and same confirmation flow.

There are no versioned migrations: this is run_sql under a name that says what the statement does.

list_tables#

List the project's tables, or describe one table's schema when 'table' is given.

Calls GET /v1/projects/:pid/tables or …/tables/:table. Under an account key the list carries row_count for every table.

create_table#

Create a table (guided) AND declare who may see and write its rows. Builds a CREATE TABLE statement from columns, applies it, then sets the access preset. Platform columns (id, owner_id, space_id, created_at, updated_at) are added by the platform — do not declare them. Types: TEXT, INTEGER, REAL, BOOLEAN, JSON. Any preset can be declared here: the table is brand new, so it holds no rows and nothing can be exposed by opening it.

Composes two calls: POST …/sql then PATCH …/tables/:table. The preset switch confirms itself, because a table that was just created is empty. If the CREATE succeeds and the switch fails, the tool says so:

⚠ The table "{table}" WAS created and exists, with the default preset "prive". Only the preset switch failed — do NOT create it again (that answers 409). Retry the switch alone with set_table_preset.

set_table_preset — human when exposing existing rows#

Change a table's access preset — who may see and write its rows (contract §2.1, §2.2.5). This is the most consequential change in the product: it alters what OTHER identities see, so the first call answers 428 with a summary and a confirmation_token; re-send with that token to apply. Opening reading to 'users' or 'anon' is refused to an agent with 401 and NO token — but ONLY when the table already holds rows: what the rule protects is data deposited under a promise, and an empty table holds none. On a table with rows, a human must do it from the dashboard.

Calls PATCH /v1/projects/:pid/tables/:table. Closing a preset, moving to a spaces preset or widening writes never need a human. Switching a non-empty table to a spaces preset answers 409. The full rules are in Access presets.

query_rows#

Read rows from a table (guided). Give an id to fetch one row, or filters to list. Filters use operators eq, neq, gt, gte, lt, lte, like, in, is (contract §1.4).

Calls GET …/tables/:table/rows or …/rows/:id. Filtering on a column named order, limit or cursor is refused before the call: these are reserved on the wire — use run_sql or rename the column. Under an account key every row is returned, whatever the preset.

insert_row#

Insert a row into a table (guided). 'values' maps column → value.

Calls POST …/tables/:table/rows. A row inserted by an account key has owner_id: null: it belongs to no end user, so on a prive or journal table no end user will ever see it. Insert a person's data through the app, with their session.

update_row#

Update a row by id (guided). 'values' maps the columns to change.

Calls PATCH …/rows/:id. Platform columns cannot be written.

delete_row#

Delete a row by id (guided).

Calls DELETE …/rows/:id. More than 40 deletions by the same account key on one project within 5 minutes answer 428 and require a signed-in human to confirm — an agent cleaning its own test data never sees this; emptying a table row by row does.