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.
| Input | Type | Required |
|---|---|---|
project | string | Yes |
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.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
sql | string | Yes | One or more SQL statements |
read_only | boolean | No | Run in a read-only transaction (writes fail). Default false. |
timeout_ms | integer 100–60000 | No | Statement timeout |
Returns { results: [{ command, rowCount, rows, … }], durationMs }.
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.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
name | string | Yes | e.g. 002_add_status |
sql | string | Yes |
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.
| Input | Type | Required |
|---|---|---|
project | string | Yes |
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.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
name | string | Yes | 3–63 characters: lowercase letters, digits, dashes |
visibility | "private" | "app-public" | No | private (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_roles | string[] | No | Private 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.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
bucket | string | Yes | |
path | string | Yes | e.g. templates/expense-policy.pdf (no leading slash) |
content_base64 | string | Yes | |
content_type | string | No | Default application/octet-stream |
upsert | boolean | No | Replace 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.
| Input | Type | Required | Description |
|---|---|---|---|
project | string | Yes | |
bucket | string | Yes | |
prefix | string | No | Folder, 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.