Reference

MCP tools

Everything an agent can call on Rowkery's MCP server: the limits every query runs under, the instructions the server gives the agent, each tool and its inputs, what the answers look like, and every refusal an agent can get back.

How agents call Rowkery

Rowkery's MCP server is the app itself, started with --mcp. Your agent's client (Claude Desktop, Claude Code or any other MCP client) starts it as a stdio server and talks to it over standard input and output:

/Applications/Rowkery.app/Contents/MacOS/Rowkery --mcp

It opens no window and no network port. Rowkery doesn't need to be open for it to work. On every call it reads the same config.json and keychain items as the app, so a change you make on the Agents page applies to the agent's next call. Connecting to agents shows how to add it to a client.

• Answers come back as one text block holding JSON. A refusal or an error comes back as one plain sentence, marked as an error, so the agent can read why and try again.
• Connections are named by the id or the name that list_connections returns. Names match without regard to case.
• Databases are optional. A call without one uses the connection's own database, or the first shared one if its own isn't shared. A SQLite connection has one database, main, whatever the call asks for.
• Tables can be written as table or schema.table. A bare name is found in whichever schema has it, the search path first when several do.
• Every call is logged to the activity log on the Agents page, with the arguments exactly as sent (cut at 4 KB), what was shared at the time, the row count, the time taken and the verdict. The log never holds rows.
• All tools are marked read-only for the client, except propose_change, which is marked as not read-only and not destructive: it only queues a change for you.

A good order for an agent is list_connections, then list_tables or search_schema, then describe_table for each table it will use, then query.

Limits

Every query an agent runs is held to these limits. They are fixed in the server, the same for every connection.

• Rows. The agent can ask for any number of rows from 1 to the maximum with max_rows. Rowkery caps the query by wrapping it in an outer SELECT … LIMIT, so the query's own ORDER BY and LIMIT stay as written. When the cap cuts the result, more is true.
• Time. On Postgres the limit is the session's statement_timeout; on SQLite the query is interrupted. Separately, Rowkery gives up on any one step that waits on the database (connecting, reading the schema, running the query) after 20 seconds.
• Big tables. Before running a query, Rowkery reads its plan. On Postgres, a plan that reads a table of more than 100,000 rows (by the planner's estimate) from start to end is refused, and the refusal names the table and its indexes so the agent can filter on one. A plain browse that stops early under the row cap is fine. On SQLite, a local file nobody else is waiting on, the query runs anyway with a note.
• Text and size. Text longer than 200 characters is cut and ends with …; binary values come back as <N bytes>. Rows stop once the JSON would pass 64 KB. Either way the answer carries a note saying so.
• Read-only. Every Postgres query runs on a read-only session (default_transaction_read_only), set again before every statement, so nothing a query does can loosen it. SQLite files are opened with writes refused.

Instructions agents get

When a client connects, the server sends it these instructions, which most agents read before their first call:

Rowkery gives read-only access to the database connections the user shared from the Rowkery app. Start with list_connections. Before writing a query, look at the tables with list_tables or search_schema and call describe_table for each table you will use, so you know its columns and indexes. Filter on indexed columns, aggregate in SQL (count, sum, group by) instead of pulling rows, and ask for no more rows than you will read. Queries are single SELECT statements; results are capped (200 rows by default, 1000 at most) and a plan that reads a table of more than 100,000 rows end to end is refused, so rewrite it with an indexed WHERE. explain shows the plan without running the query. Columns the user marked sensitive come back masked (masked: and ten hex digits; the same value always gives the same stand-in). You can return or count a masked column (on SQLite only return it) but not filter, sort, group or join on it; describe_table lists them. For a slow or stuck database, sessions shows what's running, what each session waits on and who blocks whom. Queries never change data: the session is read-only. To change data, call propose_change with the INSERT, UPDATE or DELETE statements and why: the user reviews a dry run in Rowkery and commits or rejects it, and check_proposal tells you which. Don't send a rejected change again.

Tools

list_connections

Saved Rowkery connections the user shared with MCP: id, name, engine, environment label, masked host, default database.

No inputs.

list_databases

Databases on a Postgres connection (SQLite has one, "main").

list_tables

Tables and views with approximate row counts and column counts. Cached for the session; refresh reloads the schema.

search_schema

Find tables and columns whose name contains the text. Cheaper than listing a big schema.

describe_table

Columns (type, nullability, default), primary key, indexes with their columns, foreign keys both ways and enum labels. Use it to pick indexed columns before querying.

explain

The query plan without running the query (EXPLAIN, never ANALYZE), its slowest step, one hint when a rule matches (a missing index, a sort on disk), and whether query would refuse it for reading a big table end to end.

query

Run one read-only SELECT. Returns column names once, rows as arrays, and more: true when the row cap cut the result. Capped at max_rows (default 200, max 1000); refused if the plan reads a table of over 100,000 rows end to end; 10 s timeout.

sessions

What's running on a Postgres database: each session's user, application, state, how long it has been at it, what it waits on and which sessions block it. Blockers come first; idle sessions are left out unless include_idle. Query text has its values replaced by ?, and a query on a table not shared with you is blanked.

propose_change

Ask the user to make a change to the data. Send INSERT, UPDATE and DELETE statements (no CTEs, RETURNING, UPDATE … FROM or DELETE … USING) on shared tables, with reason saying why. Nothing runs now: Rowkery shows the user a dry run and only they can commit it. Returns an id at once; call check_proposal later to learn whether it was committed, rejected or expired (after 24 h). Masked columns can't be mentioned, and functions defined in the database can't be called.

check_proposal

What became of a change sent with propose_change: waiting, committed (with rows changed), rejected (with the user's note, if any), failed or expired.

Example: a query

The agent asks which cities' kiosks took the most money in the sample database:

{
  "name": "query",
  "arguments": {
    "connection": "arcade",
    "sql": "SELECT k.city, count(*) AS sessions, sum(s.paid_cents) AS takings_cents FROM kiosk_sessions s JOIN kiosks k ON k.id = s.kiosk_id GROUP BY k.city ORDER BY takings_cents DESC",
    "max_rows": 3
  }
}

Rowkery answers with the column names once and each row as an array:

{
  "columns": ["city", "sessions", "takings_cents"],
  "elapsed_ms": 2,
  "more": true,
  "row_count": 3,
  "rows": [
    ["Utrecht", 50, 26250],
    ["Copenhagen", 50, 22500],
    ["Lyon", 50, 18750]
  ],
  "types": ["TEXT", "integer", "integer"]
}

The notes an agent can see are text over 200 chars was cut, stopped at N rows to stay under 64 KB, and on SQLite Note: this reads main.events (~250000 rows; indexed: (id)) end to end. Filter on an indexed column, or aggregate a narrower range.

What explain returns

explain takes the same sql and returns plan, one line per step (for example Seq Scan on public.orders rows≈1200000 cost 20000). It can also hold slowest_step, a hint (with hint_sql, such as a CREATE INDEX, when the hint has one) and query_would_refuse, the refusal query would give the same SQL. It reads the plan with EXPLAIN, never EXPLAIN ANALYZE, so the query never runs.

Example: a proposed change

The agent can't write, but it can ask you to. It sends the statements and a reason you'll read beside them:

{
  "name": "propose_change",
  "arguments": {
    "connection": "arcade",
    "sql": "UPDATE wallets SET balance_cents = balance_cents + 500 WHERE player_id = 7",
    "reason": "Refund the 5 euro top-up that failed on kiosk 3 yesterday.",
    "expect_rows": 1
  }
}

Nothing runs. Rowkery checks the statements, queues them for you and answers at once:

{
  "id": "p_11db31b530ca",
  "note": "Waiting for the user to review it in Rowkery. Call check_proposal with this id later; don't send it again.",
  "state": "waiting",
  "statements": 1
}

Later the agent calls check_proposal with { "id": "p_11db31b530ca" } and gets one of these:

What you see and do with it is on Proposed changes.

What a proposal may hold

• One to 20 INSERT, UPDATE and DELETE statements, run in order in one transaction when you commit. No WITH queries, no RETURNING, no UPDATE … FROM and no DELETE … USING.
• Only tables you share, on a connection that isn't Read-only.
• Only Postgres's built-in functions, as for queries, and no mention of a sensitive column.
• A reason under 1,000 characters, and SQL under 20 KB.
• At most 5 proposals can wait on one connection at a time.

The checks run when the agent proposes, and Rowkery runs them again before it shows you the dry run and again before it commits, against your settings at that moment.

Refusals and errors

Every message below is the exact text an agent gets back. Parts in capitals or quotes, such as a table name or a count, are filled in for the call.

Connections, databases and tables

list_connections itself never refuses. When some saved connections aren't shared, its answer adds not_shared with how many.

The statement

Tables you haven't shared

Big tables

Functions

Agents can call Postgres's own functions that only compute on their arguments (every immutable built-in, such as lower or count, plus a list of safe ones for dates, JSON, text search and catalog descriptions). Rowkery checks the SQL as sent and again in the plan, where views and SQL functions are expanded.

The reasons a function is refused by name:

Sensitive columns

Time

Any other error from the database, such as a syntax error or a missing column, comes back as the database's own message.

Looking at sessions

In a sessions answer, a query that reads a table you haven't shared shows as (reads a table not shared with agents), and one the login can't see as (not visible to this login).

Proposed changes

These come from propose_change. Its statements also get the table, function and sensitive-column refusals above.

How masked values look

The values of a column you mark as sensitive are never sent to an agent. In its place the agent gets a stand-in: masked: and ten hex digits.

{
  "columns": ["id", "nickname", "email"],
  "masked": ["email"],
  "rows": [
    [1, "blink_1", "masked:2bf19f676e"],
    [2, "comet_2", "masked:820c50d3e3"],
    [3, "dash_3", "masked:d6ea0aaebf"]
  ]
}

• The same value always gives the same stand-in on one connection, so an agent can still tell whether two rows hold the same email. A different connection gives different stand-ins.
• NULL stays null.
• The stand-in can't be turned back into the value. It is a keyed hash (HMAC-SHA256) under a random key Rowkery keeps for each connection in your keychain.
• The agent knows which columns are masked. describe_table lists them under masked, search_schema adds (masked) after the column, and a query's answer lists them under masked.

How to mark a column, and how Presenting hides the same columns on your screen, is on Sensitive columns and Presenting.