Skip to content

MCP tools

Generated from baguettedb at v0.1.0. The same files at any release: docs/reference on GitHub.

The MCP server of an instance exposes the tools below. An agent acts with the permissions of one account, on the bdbs that account is a member of: the owner, or the account --as names, when bdb mcp serves it over stdio; otherwise the account it signed in with or whose token it sends. A tool reserved to bdb owners says so in its description. get_docs serves two manuals an agent reads before authoring formulas or writing SQL: the formula authoring manual and the SQL capabilities and engine rules. Every session also opens with the agent instructions.

Lists all bdbs the authenticated user belongs to, with their role in each. This is the routing directory: per bdb it returns id, name, description, table names+types, and skill summaries (name, description) — no column schemas and no skill bodies. Use it to decide which bdb the task belongs to, then call describe_bdb on the chosen bdb for its full orientation. A bdb with deleted_at set is soft-deleted (purged on or after purge_at) — warn the user before working in it; restorable from the web UI until then.

Parameters: none.

Lists the starters a new bdb can be created from. Each entry carries the key to pass to create_bdb, what the starter is for, and the formulas the bdb will open with. Read it before suggesting a starter, so the suggestion names what the user actually gets.

Parameters: none.

Creates a new bdb for the user, either blank or seeded from a starter. With starter_key the bdb arrives with its tables, formulas, and skill already set up — never build a starter’s contents by hand instead. Only call this when the user has asked for a new bdb, and confirm the name with them first. Prefer an existing bdb from list_bdbs when one fits: bdbs are a limited resource and are deleted from the web app, not from here.

Parameter Type Required Description
description string no What this bdb is for. Defaults to the starter’s description.
name string no Name for the bdb. Required for a blank bdb; with starter_key it defaults to the starter’s own name.
starter_key string no Key of the starter to seed from, as listed by list_starters. Omit for a blank bdb.

Describes a single bdb: tables with their column schemas (columns and foreign keys), skills with their full bodies inlined (bdb-level and table-targeted alike), and formulas (name, description and kind — ‘view’ or ‘action’ — their SQL and parameters live in get_formula). When a bdb is too large, schemas or table-targeted skill bodies fall back to summaries and the omitted field says what to call instead. Always call this orientation tool once you have decided which bdb to work in — right after picking it from list_bdbs or being pointed at it by the user, and before querying, mutating, or running formulas there. If the bdb has deleted_at set, it has been soft-deleted by its owner and will be permanently purged on or after purge_at. Warn the user before working in this bdb and tell them they can restore it from the web UI before the purge date.

Parameter Type Required Description
bdb_id string yes Bdb ID

Renames a bdb or rewrites its description. Only the bdb’s owner can do either. Pass just the field being changed — an omitted one keeps its current value. Only call this when the user has asked for the change; confirm the new name with them first, since every member of a shared bdb sees it. Members, invites, and deletion are managed in the web app.

Parameter Type Required Description
bdb_id string yes Bdb ID
description string no New description; omit to keep the current one, pass “” to clear it
name string no New name; omit to keep the current one

Describes one table: columns, foreign keys, CHECK constraints, kind (table / view / virtual / shadow, with the virtual-table module, e.g. fts5), plus the full bodies of skills targeting it. describe_bdb normally returns all of this for every table at once — reach for this tool when a describe_bdb response’s omitted note says schemas or skill bodies were dropped, or to re-read one table without re-fetching the whole bdb.

Parameter Type Required Description
bdb_id string yes Bdb ID
table_name string yes Name of the table to describe

Executes a single read-only SELECT statement. Multi-statement input is not supported. Results are capped: a larger result is refused with the limit named in the error, so add a LIMIT or aggregate for big tables. The full JSON1 function set, JSONB, and FTS5 are built in — engine capabilities, rules and your limits in get_docs(topic: ‘sql’).

Parameter Type Required Description
bdb_id string yes Bdb ID
sql string yes Single SELECT statement to execute

Writes data: executes one or more DML statements (INSERT, UPDATE, DELETE) atomically. Multiple statements separated by ‘;’ run in a single transaction; if any fails the whole request is rolled back. All statements share one batch_id and produce a single undo entry. The statement and affected-row caps are listed in get_docs(topic: ‘sql’) and named in a refusal. For schema changes use execute_schema; for read-only queries use execute_query. JSON values bind and store as TEXT, with the full JSON1 set usable in DML. BLOB values cannot be stored (keep binary as base64 or hex text) — engine capabilities and rules in get_docs(topic: ‘sql’).

Parameter Type Required Description
bdb_id string yes Bdb ID
sql string yes DML statement(s) to execute; multiple separated by ‘;’

Executes one or more DDL statements (CREATE/ALTER/DROP TABLE/INDEX/VIEW/TRIGGER) atomically. Multiple statements separated by ‘;’ run in a single transaction; if any fails, all are rolled back. The statement cap is listed in get_docs(topic: ‘sql’). Every created or renamed-to name (tables, columns, indexes, views, triggers) must start with a letter and contain only ASCII letters, digits, and underscores, at most 128 chars. SQL keywords (e.g. ‘order’) are allowed but best avoided — every later query has to double-quote them. Note: ALTER TABLE RENAME TO is single-statement only, and statements that reference objects created by an earlier statement in the same request (e.g. CREATE TABLE foo; CREATE INDEX ON foo) must be split into separate requests. Declare JSON-holding columns TEXT with CHECK (json_valid(col)); expression indexes on json_extract(…) are supported. BLOB columns can be declared but cannot hold BLOB values (binary belongs in TEXT as base64 or hex) — engine capabilities and rules in get_docs(topic: ‘sql’).

Parameter Type Required Description
bdb_id string yes Bdb ID
sql string yes DDL statement(s) to execute; multiple separated by ‘;’

Lists recent changes (data and schema) in this bdb, grouped by batch. By default returns changes from all users; pass user_id to scope to one author, kind (‘DML’ or ‘DDL’) to filter by category, or table_name to filter to a single table (matches DML target tables and DDL object names). Each entry carries id (change_log_id), batch_id, and kind; pass id or batch_id to revert_change to undo a specific change. Entries written by undo, redo, or revert record the statement that ran (a column restored by undo appears as its ADD COLUMN). Note: virtual tables (e.g. FTS5) are captured only at the DDL level — direct row writes bypass the change log, and undo of DROP returns an empty vtable to be rebuilt from the source.

Parameter Type Required Description
bdb_id string yes Bdb ID
kind string no ‘DML’ for data changes, ‘DDL’ for schema changes; omit to return both
limit string no Max number of entries to return (default 20, max 100)
table_name string no Filter to a single table (DML target or DDL object name)
user_id string no UUID — scopes results to changes by this user; omit to return all users

Reverses your most recent change in this bdb, data or schema; other members’ history is untouched. Call repeatedly to walk back further. The undone batch moves to your redo stack (redo_last_change). To reverse a specific entry by anyone, use revert_change.

Parameter Type Required Description
bdb_id string yes Bdb ID

Re-applies your most recently undone change in this bdb (data or schema). Any new change you make clears your redo stack; other members’ activity does not.

Parameter Type Required Description
bdb_id string yes Bdb ID

Reverts a specific change (data or schema) by executing its inverse. Targets any user’s change in this bdb — call list_changes first to find the change_log_id or batch_id. Pass either a single change_log_id or a batch_id to revert all entries in that batch. The revert lands on your own undo stack, so you can undo it via undo_last_change.

Parameter Type Required Description
bdb_id string yes Bdb ID
batch_id string no Batch ID to revert all entries from a single change (provide this OR change_log_id)
change_log_id string no Change log entry ID to revert (provide this OR batch_id)

Owner-only: reverses the most recent change in this bdb regardless of who made it (data or schema). The reversed batch lands on YOUR redo stack (redo_last_change_anyone). Inspect the timeline with list_changes first.

Parameter Type Required Description
bdb_id string yes Bdb ID

Owner-only: re-applies the most recently undone change in this bdb regardless of who undid it. The re-applied batch lands on YOUR undo stack.

Parameter Type Required Description
bdb_id string yes Bdb ID

Lists every formula in the bdb (name, description, kind, SQL, parameter schema, display config, hidden flag), ordered by display position then name. Hidden formulas are included — hiding only trims the members’ app listing, never this tool.

Parameter Type Required Description
bdb_id string yes Bdb ID

Fetches a single formula (with its SQL and parameter schema) by name or UUID. Useful to re-read a formula’s definition before running or updating it.

Parameter Type Required Description
bdb_id string yes Bdb ID
ref string yes Formula reference: the name or the UUID.

Creates a formula: a named, parameterized SQL artifact members run from the app and you run via run_formula. The kind is derived from the SQL — a single SELECT is a ‘view’ (read); one or more INSERT/UPDATE/DELETE statements separated by ‘;’ are an ‘action’ (write, atomic). No DDL, and reads and writes cannot mix. Use NAMED bind parameters (e.g. :status), each declared in params. Before your first create_formula or update_formula call in a conversation, call get_docs(topic: ‘formulas’) — the full authoring manual (params and their sources, display modes, slots, nested details).

Parameter Type Required Description
bdb_id string yes Bdb ID
name string yes Slug-shaped name, unique per bdb: lowercase letters, digits and hyphens, starting with a letter (e.g. ‘low-stock’).
description string yes One-line description, shown in listings for routing.
sql string yes The SQL: a single SELECT for a view, or one or more DML statements separated by ‘;’ for an action, using named bind parameters.
attached_to_formula_id string no UUID of the view this formula attaches to (as its row/bulk action or row detail). Omit for a top-level formula.
display object no Presentation config for a view. At create time only slot-free configs pass — attach the actions first, then set slots via update_formula.
display_order number no Position among siblings (lower sorts first). Omit to append.
hidden boolean no Marks the formula assistant-only: omitted from the members’ formula list; MCP tools always see it.
label string no Human name shown in the app instead of the slug; presentation only — the name stays the reference. Omit to show the name itself.
params array of object no Ordered parameter schema. One entry per named bind parameter the SQL uses.

display fields:

  • columns (array of object): Per-column presentation, one entry per result column: a role and/or format, or hidden.
    • column (string, required)
    • format (string, one of markdown)
    • hidden (boolean)
    • role (string, one of title, body, check, group, day)
  • mode (string, one of table, checklist, cards, board, calendar)
  • slots (object): Interaction slots, each naming a formula ATTACHED to this view (name or UUID).
    • add (string): Insert action; prompt/lookup params only.
    • bulk (array of string): Ordered :rowids actions filling the selection toolbar (table mode only).
    • delete (string): Delete action with :rowid + optional extras.
    • detail (string): A :rowid SELECT view rendered on row tap.
    • edit (string): Any-verb action with :rowid + at least one prompt/lookup param (seeded form).
    • move (string): Update action with :rowid + one target param: option-declaring (board) or date (calendar).
    • reorder (string): Update action with :ordered_rowids, enabling drag-to-reorder.
    • row_actions (array of string): Formula refs (name or UUID) giving the per-row menu in order: extra single-row actions, plus optionally the formula filling the edit, delete, or detail slot, which places that built-in entry (unlisted ones trail as Details, Edit, Delete).
    • toggle (string): Any-verb action flipping the check-role column; :rowid + optional extras.
  • window (object): Calendar only: the days shown. EITHER a weekly window (week_start/week_end weekday names, default monday..sunday, week_start alone = a full week from it, repeats every 7 days) OR a fixed range (start YYYY-MM-DD + days 1..31, default 7, steps by its length). Never both.
    • days (integer): Length of a fixed range in days, 1..31.
    • start (string): First day of a fixed range, YYYY-MM-DD.
    • week_end (string, one of monday, tuesday, wednesday, thursday, friday, saturday, sunday): Last weekday of a weekly window; may wrap past week_start.
    • week_start (string, one of monday, tuesday, wednesday, thursday, friday, saturday, sunday): First weekday of a weekly window.

params entries:

  • name (string, required): Bind parameter name without the colon (e.g. ‘status’ for :status).
  • type (string, required, one of text, integer, float, boolean, date, datetime, time, group)
  • source (string, required, one of prompt, selection-single, selection-bulk, pagination, lookup, reorder, window)
  • default (string): Value an omitted optional param binds, in string form, coerced to the type; on a multi-select only the literal ‘all’.
  • defaults (array): A multi-select’s declared subset — the values an omitted param binds.
  • fields (array of object): Group-only: the per-row schema — scalar prompt/lookup entries, no nested groups.
  • hint (string): Display-only input placeholder; never affects binding.
  • inline (boolean): Display-only: places the param in the add slot’s quick-add form.
  • lookup (object): Required for source ‘lookup’: a picker over table — label_column shown, value_column bound.
    • table (string, required)
    • label_column (string, required)
    • value_column (string, required)
    • allow_new (boolean)
    • exclude_selection (boolean)
    • fill (object)
    • scope (object)
  • multiline (boolean): Display-only: renders the input as a textarea (prompt text params only).
  • multiple (boolean): Multi-select (a lookup, or a prompt param with options): the run value is an array binding as ONE JSON TEXT value.
  • optional (boolean): The caller may omit the param; it binds ‘default’ when declared, else SQL NULL.
  • options (array): Closed, ENFORCED vocabulary for a prompt param; runs pass values, never labels.
  • when (object): Conditional visibility: the field renders only while the sibling param compares true against value under op (default eq).
    • param (string, required)
    • value (string, required)
    • op (string, one of eq, ne, lt, lte, gt, gte)

Updates an existing formula resolved by name or UUID. Pass only the fields to change; omitted fields are left untouched. Same conventions as create_formula — call get_docs(topic: ‘formulas’) before authoring. Changing sql re-derives the kind and verb; params replaces the whole schema. display is tri-state: omit = unchanged, null = clear, an object = replace — this is where slots are set (refs by name or UUID).

Parameter Type Required Description
bdb_id string yes Bdb ID
ref string yes Formula reference: the name or the UUID.
description string no New one-line description.
display object no New presentation config, same shape as create_formula’s display. Pass null to clear back to the plain table; omit to leave unchanged.
display_order number no New position among siblings.
hidden boolean no New hidden flag: true = assistant-only; false = listed for everyone.
label string no New human name; pass an empty string to drop it.
name string no New slug-shaped name, unique per bdb.
params array of object no Replacement parameter schema; entries take the same shape as create_formula’s params. Omit to leave the schema unchanged.
sql string no New SQL: a single SELECT for a view, or ‘;’-separated DML statements for an action.

Deletes a formula resolved by name or UUID. Formulas attached to a deleted view (its row/bulk actions and row detail) are removed with it.

Parameter Type Required Description
bdb_id string yes Bdb ID
ref string yes Formula reference: the name or the UUID.

Runs a formula by name or UUID, with every declared parameter supplied in params as name → value (an optional parameter may be omitted). A view returns rows — run again with cursor set to the response’s next_cursor when a pagination block reports has_more — and needs read permission; an action runs atomically as one write (one undo entry), returns the affected-row count, and needs write permission. Selection params bind as rowid / rowids / parent_rowid; group and multi-select lookup params take arrays — full passing rules in get_docs(topic: ‘formulas’).

Parameter Type Required Description
bdb_id string yes Bdb ID
ref string yes Formula reference: the name or the UUID.
params object no Parameter values keyed by name (e.g. {“status”: “open”, “rowids”: [3, 7]}). Omit a parameter to leave a pagination control at its default.

Fetches a single skill (with body) by name or UUID. Useful when you need to re-read a specific skill body that’s no longer in context.

Parameter Type Required Description
bdb_id string yes Bdb ID
ref string yes Skill reference: either the human-readable name (e.g. ‘groceries-flow’) or the UUID

Creates a new skill in the bdb. Skills teach agents how to work with one or more tables (or with the bdb as a whole if target_tables is empty).

Keep the skill concise. Every skill body is loaded into agent context by describe_bdb (table-targeted bodies also appear in describe_table for their tables). Long skills bloat context for every future interaction in this bdb — aim for the minimum content that conveys the rule clearly.

Note: deletion is only available via the web UI — ask the user to delete the skill there if needed.

Parameter Type Required Description
bdb_id string yes Bdb ID
name string yes Slug-shaped human-readable name, unique per bdb. Lowercase letters, digits and hyphens; must start with a letter (e.g. ‘groceries-flow’).
description string yes One-line description; appears alongside the name in list_bdbs and describe_bdb for routing.
body string yes Full markdown body of the skill (max 100 KB).
target_tables array of string no Tables this skill targets. Empty (or omitted) for a bdb-level skill.

Updates an existing skill. Pass only the fields you want to change; omitted fields are left untouched. To replace target tables, pass the full new list (an empty array converts the skill into a bdb-level skill).

Keep the skill concise. Every skill body is loaded into agent context by describe_bdb (table-targeted bodies also appear in describe_table for their tables). Long skills bloat context for every future interaction in this bdb — aim for the minimum content that conveys the rule clearly.

Note: deletion is only available via the web UI — ask the user to delete the skill there if needed.

Parameter Type Required Description
bdb_id string yes Bdb ID
ref string yes Skill reference: name or UUID.
body string no New markdown body (max 100 KB).
description string no New one-line description.
name string no New name (slug-shaped, unique per bdb).
target_tables array of string no Replacement target table list. Pass an empty array to convert to a bdb-level skill. Omit to leave targets unchanged.

Returns the full built-in reference documentation for one topic: ‘formulas’ — the formula-authoring manual (naming, params and their sources, display modes, slots, nested details); ‘sql’ — SQL capabilities and engine rules (identifier rules, the reserved ‘_’ prefix, JSON1/JSONB, FTS5, change-log semantics including the no-BLOB rule, statement limits). Fetch a topic once per conversation, before the first call that needs it.

Parameter Type Required Description
topic string yes Documentation topic to fetch. One of formulas, sql.