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.
list_bdbs
Section titled “list_bdbs”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.
list_starters
Section titled “list_starters”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.
create_bdb
Section titled “create_bdb”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. |
describe_bdb
Section titled “describe_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 |
update_bdb
Section titled “update_bdb”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 |
Schema and data
Section titled “Schema and data”describe_table
Section titled “describe_table”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 |
execute_query
Section titled “execute_query”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 |
execute_data
Section titled “execute_data”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 ‘;’ |
execute_schema
Section titled “execute_schema”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 ‘;’ |
History
Section titled “History”list_changes
Section titled “list_changes”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 |
undo_last_change
Section titled “undo_last_change”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 |
redo_last_change
Section titled “redo_last_change”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 |
revert_change
Section titled “revert_change”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) |
undo_last_change_anyone
Section titled “undo_last_change_anyone”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 |
redo_last_change_anyone
Section titled “redo_last_change_anyone”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 |
Formulas
Section titled “Formulas”list_formulas
Section titled “list_formulas”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 |
get_formula
Section titled “get_formula”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. |
create_formula
Section titled “create_formula”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 ofmarkdown)hidden(boolean)role(string, one oftitle,body,check,group,day)
mode(string, one oftable,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 ofmonday,tuesday,wednesday,thursday,friday,saturday,sunday): Last weekday of a weekly window; may wrap past week_start.week_start(string, one ofmonday,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 oftext,integer,float,boolean,date,datetime,time,group)source(string, required, one ofprompt,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 overtable— 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 siblingparamcompares true againstvalueunderop(default eq).param(string, required)value(string, required)op(string, one ofeq,ne,lt,lte,gt,gte)
update_formula
Section titled “update_formula”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. |
delete_formula
Section titled “delete_formula”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. |
run_formula
Section titled “run_formula”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. |
Skills
Section titled “Skills”get_skill
Section titled “get_skill”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 |
create_skill
Section titled “create_skill”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. |
update_skill
Section titled “update_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. |
Reference
Section titled “Reference”get_docs
Section titled “get_docs”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. |