Skip to main content

Tools: data and storage

These tools are for the project's owner, people with the developer app role and org admins. Auditors can use the read-only ones.

describe_schema​

The project database's tables, columns, primary keys, relationships and row-level security policies (in plain English), plus the platform's SQL helpers.

InputTypeRequired
projectstringYes

Returns { database, tables: […], … }. The summary says how many tables there are.

run_sql​

Runs SQL against the project database as its owner: row-level security is bypassed. Audited. A statement timeout applies (default 15 s). Returns up to 200 rows per statement.

InputTypeRequiredDescription
projectstringYes
sqlstringYesOne or more SQL statements
read_onlybooleanNoRun in a read-only transaction (writes fail). Default false.
timeout_msinteger 100–60000NoStatement timeout

Returns { results: [{ command, rowCount, rows, … }], durationMs }.

tip

For schema changes you want to keep and replay, use apply_migration instead.

apply_migration​

Applies a named schema migration once, in a transaction, and records it in tc.migrations. It's the same as shipping db/migrations/<name>.sql in a deploy.

InputTypeRequiredDescription
projectstringYes
namestringYese.g. 002_add_status
sqlstringYes

Returns { name, status, checksum }, where status is applied or already_applied. Re-applying the same name and SQL is a no-op; changed SQL under an applied name is refused with MIGRATION_CHANGED (write a new migration).

New tables should enable row-level security and add policies in the same migration:

create table expenses (
id bigint generated by default as identity primary key,
amount numeric(12,2) not null,
created_by text not null default tc.user_id()
);
alter table expenses enable row level security;
create policy "own rows" on expenses for all to tc_user
using (created_by = tc.user_id()) with check (created_by = tc.user_id());

list_buckets​

A project's storage buckets, usage against quota, and the per-file limit.

InputTypeRequired
projectstringYes

Returns { buckets, usage, sdk }, where sdk is a one-line reminder of the tc.storage calls.

create_bucket​

Creates (or updates) a storage bucket. Buckets can also be declared in tc.json.

InputTypeRequiredDescription
projectstringYes
namestringYes3–63 characters: lowercase letters, digits, dashes
visibility"private" | "app-public"Noprivate (default): each person reads their own files, read_roles read all, others need a signed URL. app-public: everyone who can open the app reads every file.
read_rolesstring[]NoPrivate buckets: app roles that read every file, e.g. ["approver"]

There is no internet-public option. Anyone with app access can upload; only the uploader (or the editor/admin app roles) can replace or delete a file.

upload_file​

Uploads a small file (up to 5 MB, base64) as you; you become its owner. The type is checked from the bytes, and HTML, SVG and scripts are refused.

InputTypeRequiredDescription
projectstringYes
bucketstringYes
pathstringYese.g. templates/expense-policy.pdf (no leading slash)
content_base64stringYes
content_typestringNoDefault application/octet-stream
upsertbooleanNoReplace an existing file. Default false.

Errors: TOO_LARGE_FOR_MCP over 5 MB (use tc storage put), plus the storage codes (STORAGE_EXISTS, STORAGE_TYPE_NOT_ALLOWED, …) with their fixes.

list_files​

Files and folders in a bucket under a folder prefix, with owner, size, type and last-modified time.

InputTypeRequiredDescription
projectstringYes
bucketstringYes
prefixstringNoFolder, e.g. 2026/. Default: the bucket root.

Returns { bucket, prefix, folders: string[], objects: […], next }. Up to 1000 entries; next is set when there are more.

Was this page helpful?