MCP server

@vaifstudio/mcp is a Model Context Protocol server. It lets an AI coding tool read and change your VAIF Studio project: tables and rows, SQL, storage, functions, secrets, API keys and realtime. It runs on your machine with npx -y @vaifstudio/mcp, so most tools need no install step. To install it globally instead:

npm install -g @vaifstudio/mcp

Note

@vaifstudio/mcp 1.7.0 is the current release. It is not on npm yet.

Set it up in Claude Code, Claude Desktop, Cursor, VS Code, Codex or Windsurf.

Settings

Variable	Needed for	Where it comes from
VAIF_PROJECT_ID	Everything	Your project ID, from the console or vaif.config.json
VAIF_API_KEY	The row tools (query_rows, insert_row and the rest) and signed file links	A project API key, from the project’s Overview or Project settings > API keys. get_signed_url needs a key with the storage scope
VAIF_AUTH_TOKEN	Schema, SQL, storage, functions and key tools	Optional. Without it, the server uses the sign-in that vaif login saved in ~/.vaif/auth.json, read again on every call
VAIF_API_URL	A local or self-hosted API only	Defaults to https://api.vaif.studio

Keep API keys out of files you commit.

Tools and what they can change

Every tool has a title and the MCP safety labels (readOnlyHint, destructiveHint, idempotentHint and openWorldHint). Clients use them to tell a read from a change, and many ask before running anything that is not read-only.

Tools	What they can change
list_tables, describe_table, query_rows, get_schema	Nothing: read-only
list_buckets, list_files, get_signed_url, list_storage_policies, list_functions, list_secrets, get_function_logs, list_api_keys, realtime_status	Nothing: read-only
execute_sql	Nothing, unless you pass allow_writes: true
insert_row, create_bucket, create_function, create_storage_policy, create_api_key, enable_realtime	Adds, never overwrites
update_row, delete_row, create_tables, deploy_function, set_secret, delete_secret	Changes or deletes
invoke_function	Runs your code, which can do anything it is written to do

There are also four guided prompts: setup-backend, add-feature, generate-api-code and debug-query.

Run SQL with execute_sql

execute_sql runs SQL against the project’s database, and it is read-only unless you ask for writes:

• By default the request is marked read-only. The API refuses any statement that writes, and runs the rest in a READ ONLY transaction, so a write hidden inside a database function is refused too.
• allow_writes: true runs INSERT, UPDATE, DELETE and schema changes.
• In a production environment, a write also needs allow_production: true and an owner or admin role, and it is written to the audit log. Reads need neither flag.
• A write is never retried, and at most 200 rows are returned to the model.

{
  "sql": "SELECT status, count(*) FROM orders GROUP BY status"
}

{
  "sql": "UPDATE orders SET status = 'refunded' WHERE id = $1",
  "params": ["ord_123"],
  "allow_writes": true
}

Review what an AI tool changes in your project as you would a teammate’s change.