@vaif/mcp

MCP (Model Context Protocol) server for VAIF Studio. Connect Claude Code, Cursor, or any MCP-compatible AI assistant directly to your VAIF project to query databases, manage storage, invoke functions, and inspect schemas.

Installation

npm install -g @vaif/mcp

Or run directly with npx:

npx @vaif/mcp --api-key vk_xxx --project-id proj_xxx

Usage with Claude Code

Add the VAIF MCP server to Claude Code:

claude mcp add vaif-studio -- npx @vaif/mcp --api-key vk_xxx --project-id proj_xxx

Or with environment variables:

export VAIF_API_KEY=vk_xxx
export VAIF_PROJECT_ID=proj_xxx
claude mcp add vaif-studio -- npx @vaif/mcp

Configuration

Configuration is resolved in priority order:

1. CLI Flags (highest priority)

| Flag | Description | |------|-------------| | --api-key <key> | VAIF API key (vk_...) | | --project-id <id> | VAIF project ID (proj_...) | | --api-url <url> | API URL (default: https://api.vaif.studio) | | --auth-token <token> | JWT auth token |

2. Environment Variables

| Variable | Description | |----------|-------------| | VAIF_API_KEY | API key | | VAIF_PROJECT_ID | Project ID | | VAIF_API_URL | API URL | | VAIF_AUTH_TOKEN | Auth token |

3. Local Config File

vaif.config.json in the current working directory:

{
  "projectId": "proj_xxx",
  "api": {
    "apiKey": "vk_xxx"
  }
}

4. User Auth File (lowest priority)

~/.vaif/auth.json:

{
  "token": "eyJhbG...",
  "projectId": "proj_xxx"
}

Authentication

The server supports two authentication modes:

• API Key (--api-key / VAIF_API_KEY): Used for data plane operations (CRUD on database tables via generated REST endpoints).
• Auth Token (--auth-token / VAIF_AUTH_TOKEN / ~/.vaif/auth.json): JWT used for control plane operations (schema introspection, storage, functions, project info). Falls back to data-plane writes when no API key is configured.

You can provide both for full access to all tools, or just one depending on your needs. When using the on-disk JWT path (~/.vaif/auth.json written by vaif login), the token is re-read on every request — so refreshing via vaif login takes effect without restarting the MCP server.

If both --api-key and the JWT are missing, write tools surface:

[VAIF MCP] Not authenticated. Run `vaif login` in a terminal to refresh.

Available Tools

Database

| Tool | Description | |------|-------------| | list_tables | List all tables in the project database | | describe_table | Describe a table's columns, types, and constraints | | query_rows | Query rows with filtering, sorting, and pagination | | insert_row | Insert a new row into a table | | update_row | Update an existing row by ID | | delete_row | Delete a row by ID |

Auth

| Tool | Description | |------|-------------| | list_api_keys | List all API keys for the project | | create_api_key | Create a new project-scoped API key |

Storage

| Tool | Description | |------|-------------| | list_buckets | List all storage buckets | | list_files | List files in a bucket with optional path prefix | | get_signed_url | Generate a temporary signed download URL | | create_bucket | Create a new storage bucket (public or private) | | list_storage_policies | List RLS-style access policies on a bucket | | create_storage_policy | Create an access policy for a storage bucket |

Functions

| Tool | Description | |------|-------------| | list_functions | List all serverless functions (source excluded by default; pass include_source=true for full code) | | invoke_function | Invoke a function by name or UUID with an optional JSON payload | | create_function | Create a new serverless function definition | | deploy_function | Deploy source code to a function by name or UUID | | set_secret | Create or update a function secret | | list_secrets | List all secret names (values hidden) | | delete_secret | Delete a secret by ID | | get_function_logs | Get execution logs by function name or UUID, with optional status filter |

Realtime

| Tool | Description | |------|-------------| | realtime_status | Check which tables have realtime enabled | | enable_realtime | Enable realtime subscriptions on specific tables |

Schema

| Tool | Description | |------|-------------| | get_schema | Get the full database schema as JSON |

Available Prompts

Prompts are guided workflows that appear when you type /mcp in Claude Code. They provide context-aware templates for common tasks.

| Prompt | Description | |--------|-------------| | setup-backend | Set up a new backend from scratch — design tables, seed data, and generate SDK code | | add-feature | Add a new feature to an existing backend — create tables, functions, and storage | | generate-api-code | Generate TypeScript SDK code for your current schema (auto-fetches schema) | | debug-query | Debug a failing query — inspect schema, test queries, and get the fix |

Using prompts

In Claude Code, type /mcp and select a prompt, or reference them directly:

> /mcp setup-backend
Description: a task management app with teams and projects

> /mcp debug-query
Issue: filter on metadata->status not working

Available Resources

| Resource | URI | Description | |----------|-----|-------------| | Schema | vaif://schema | Full database schema (tables, columns, types, relationships) | | Project Info | vaif://project-info | Project metadata (name, region, settings) |

CLAUDE.md Integration

For AI-assisted development with Claude Code, add a CLAUDE.md file to your project root. The MCP server works alongside CLAUDE.md to give Claude full context about your VAIF project.

See packages/mcp/CLAUDE.md for a template you can customize, or generate one automatically:

npx @vaif/cli init --claude

This generates a personalized CLAUDE.md with your actual table names, function names, storage buckets, and plan limits.

Examples

Query database rows

> Use the query_rows tool to get the 10 most recent users

Using query_rows with table="users", limit=10, order_by="created_at", order="desc"

Filter with operators

> Find all orders where total is greater than 100

Using query_rows with table="orders", filter={"total.gt": "100"}

Inspect schema

> What tables are in my database?

Using list_tables
→ ["users", "orders", "products", "categories"]

Invoke a function

> Run the send-welcome-email function for user 123

Using invoke_function with function="send_welcome_email", payload={"userId": "123"}

Functions can be invoked by name or UUID — names are resolved automatically using the configured project ID.

Create a storage bucket

> Create a private bucket called "avatars"

Using create_bucket with name="avatars", public=false

Enable realtime on a table

> Enable realtime subscriptions on the messages table

Using enable_realtime with tables=["messages"]

Deploy a function

> Create and deploy a hello_world function

Using create_function with name="hello_world", runtime="nodejs20"
Using deploy_function with function="hello_world", source="export default async..."

View function logs

> Show me recent errors for the send_email function

Using get_function_logs with function="send_email", status="error", limit=10

Function naming: Names must be alphanumeric and underscores only (^[a-zA-Z0-9_]+$). Use send_email not send-email.

Auth Modes

VAIF uses two authentication modes. The MCP server handles both automatically:

| Auth Mode | Header | Used For | |-----------|--------|----------| | API Key | x-api-key: vk_xxx | Data-plane: CRUD on tables (/generated/*), storage uploads/downloads | | JWT Token | Authorization: Bearer <jwt> | Control-plane: schema introspection, project management, function CRUD/invoke, bucket creation |

All control-plane requests include the x-project-id header automatically, enabling function invocation by name.

Note: The MCP server uses both auth modes automatically when both are configured (which vaif claude-setup does by default).

Limitations

• Sub-agents: MCP tools are only available to the main Claude Code session, not to spawned sub-agents via the Task tool. The main session should handle all VAIF backend operations directly.

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Watch mode
pnpm dev

# Type check
pnpm typecheck

License

MIT