MCP tools

The engine serves MCP over streamable HTTP at /mcp, with the same bearer tokens and scopes as the REST API. See Use from an AI agent to connect a client.

Tool	Read-only	Destructive	What it does
create_branch	no	no	Create a branch as a full copy of another branch (default: the default branch). Changes on it never merge back. Use it to test migrations safely.
create_database	no	no	Create a database with an empty default branch named main. Needs an instance admin token. Names: lowercase letters, digits and hyphens.
create_snapshot	no	no	Take a snapshot of a branch. Restoring one later makes a new branch; it never overwrites.
delete_branch	no	yes	Delete a branch and its data. Protected branches and the default branch can’t be deleted. This can’t be undone.
diff_branches	yes	no	Compare the schema (tables, columns, indexes, views, triggers) of a branch against another branch. Data isn’t compared.
execute	no	yes	Run one SQL statement that changes data or schema (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP) in its own transaction. Needs a write token. Prefer testing schema changes on a branch first. Rows from RETURNING are shown up to 1000 rows and about 64 KB.
get_database	yes	no	Get one database: its id, default branch, branch count and size.
get_schema	yes	no	Get a branch’s schema: tables with their columns, indexes, views and triggers, with the CREATE statements. Pass table to get one table with its indexes and triggers. A schema over about 64 KB comes back as names only.
list_branches	yes	no	List a database’s branches, marking the default and protected ones.
list_databases	yes	no	List the databases this token can see, with their default branch and size.
list_snapshots	yes	no	List a branch’s snapshots, newest first.
query	yes	no	Run one read-only SQL statement (SELECT, PRAGMA table_info, …) on a read-only connection. Returns at most max_rows rows (default 100) and about 64 KB; truncated results say so.
reset_branch	no	yes	Throw away a branch’s changes by copying its parent again. Not allowed on protected branches or the default branch.

create_branch

Create a branch as a full copy of another branch (default: the default branch). Changes on it never merge back. Use it to test migrations safely.

Input	Type	Description
database (required)	string	database name or id
expires_in_days	integer	delete the branch automatically after this many days
from	string	branch to copy; defaults to the default branch
name (required)	string	name for the new branch: lowercase letters, digits and hyphens

create_database

Create a database with an empty default branch named main. Needs an instance admin token. Names: lowercase letters, digits and hyphens.

Input	Type	Description
name (required)	string	lowercase letters, digits and hyphens, starting with a letter or digit

create_snapshot

Take a snapshot of a branch. Restoring one later makes a new branch; it never overwrites.

Input	Type	Description
branch	string	branch name or id; defaults to the default branch
database (required)	string	database name or id
label	string	a note to find the snapshot by

delete_branch

Delete a branch and its data. Protected branches and the default branch can’t be deleted. This can’t be undone.

Input	Type	Description
branch (required)	string	branch name or id to delete
database (required)	string	database name or id

diff_branches

Compare the schema (tables, columns, indexes, views, triggers) of a branch against another branch. Data isn’t compared.

Input	Type	Description
against	string	the branch to compare with; defaults to the default branch
branch (required)	string	the branch with the changes
database (required)	string	database name or id

execute

Run one SQL statement that changes data or schema (INSERT, UPDATE, DELETE, CREATE, ALTER, DROP) in its own transaction. Needs a write token. Prefer testing schema changes on a branch first. Rows from RETURNING are shown up to 1000 rows and about 64 KB.

Input	Type	Description
args	null or array	values for ? placeholders, in order: strings, numbers, booleans or null
branch	string	branch name or id; defaults to the default branch
database (required)	string	database name or id
sql (required)	string	exactly one SQL statement

get_database

Get one database: its id, default branch, branch count and size.

Input	Type	Description
database (required)	string	database name or id

get_schema

Get a branch’s schema: tables with their columns, indexes, views and triggers, with the CREATE statements. Pass table to get one table with its indexes and triggers. A schema over about 64 KB comes back as names only.

Input	Type	Description
branch	string	branch name or id; defaults to the default branch
database (required)	string	database name or id
table	string	only this table, with its indexes and triggers

list_branches

List a database’s branches, marking the default and protected ones.

Input	Type	Description
database (required)	string	database name or id

list_databases

List the databases this token can see, with their default branch and size.

No inputs.

list_snapshots

List a branch’s snapshots, newest first.

Input	Type	Description
branch	string	branch name or id; defaults to the database’s default branch
database (required)	string	database name or id

query

Run one read-only SQL statement (SELECT, PRAGMA table_info, …) on a read-only connection. Returns at most max_rows rows (default 100) and about 64 KB; truncated results say so.

Input	Type	Description
args	null or array	values for ? placeholders, in order: strings, numbers, booleans or null
branch	string	branch name or id; defaults to the default branch
database (required)	string	database name or id
max_rows	integer	most rows to return, 1 to 1000; default 100
sql (required)	string	exactly one SQL statement

reset_branch

Throw away a branch’s changes by copying its parent again. Not allowed on protected branches or the default branch.

Input	Type	Description
branch (required)	string	branch name or id to reset
database (required)	string	database name or id