MCP server

@capydb/mcp - let MCP-capable agents manage projects, previews, backups, restores, imports, and run SQL through the CapyDB API.

What it is

@capydb/mcp is the official Model Context Protocol server for CapyDB. It runs over stdio, talks to the control-plane REST API, and gives MCP-capable agents (Claude Code, Claude Desktop, Cursor, anything else speaking MCP) a typed tool surface for projects, preview databases, backups, restores, imports, live SQL, and observability.

Every tool returns structured JSON; API failures surface as MCP tool errors carrying the control plane's error message. Tools that trigger asynchronous jobs return the job to poll with get_job (create_project is the exception: it waits up to 5 minutes for the provision job itself).

Requires Node.js ≥ 24.21.0.

For an agent that is already looking at the dashboard in a WebMCP-capable browser, browser tools cover the same ground with no server and no API key - a narrower surface, gated on your approval for anything that writes.

Configuration

Environment variable	Required	Default	Description
`CAPYDB_API_KEY`	no	-	Org or project-scoped API key (`capy_live_...`); overrides everything else when set
`CAPYDB_API_URL`	no	`https://capydb.dev/api/capydb`	Control-plane base URL

Credentials resolve in order: CAPYDB_API_KEY, then the CapyDB CLI's saved login (the active organization in the shared config file), then a first-run browser device login - the first tool call returns an approval URL, and once approved the minted key is saved back into the CLI config.

A key passed via CAPYDB_API_KEY is read from the environment and never persisted or logged by the server. Keys from the CLI login or the device-login flow are stored locally in the CLI config file (~/Library/Application Support/capydb/config.json on macOS, $XDG_CONFIG_HOME/capydb/config.json on Linux, %AppData%\capydb\config.json on Windows) with 0600 permissions, so the CLI and the MCP server share one credential and one revocation point.

Install

No install step when your client can launch commands - use npx -y @capydb/mcp. For a global binary:

npm install -g @capydb/mcp   # provides the `capydb-mcp` executable
# or: pnpm add -g @capydb/mcp

Claude Code

claude mcp add capydb --env CAPYDB_API_KEY=capy_live_... -- npx -y @capydb/mcp

Omit --env CAPYDB_API_KEY=... to reuse the CLI's saved login or trigger the browser device login on first use.

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "capydb": {
      "command": "npx",
      "args": ["-y", "@capydb/mcp"],
      "env": {
        "CAPYDB_API_KEY": "capy_live_..."
      }
    }
  }
}

Generic MCP client (stdio)

{
  "command": "capydb-mcp",
  "env": {
    "CAPYDB_API_KEY": "capy_live_...",
    "CAPYDB_API_URL": "https://capydb.dev/api/capydb"
  }
}

Tools

Tool	What it does
`list_regions`	Regions a project can be placed in - use before `create_project`, or omit the region to let CapyDB pick.
`get_usage`	Organization storage, connection, and database counts against plan limits, with a per-project breakdown. The organization is derived from the key's projects.
`create_project`	Create a project (`environment`: `production` default, or `non_production`); waits up to 5 minutes for the provision job. The plan is derived from the organization's billing state.
`list_projects`	Projects visible to the key with state, plan, region, and storage limits. No credentials.
`get_project`	One project by id, including provisioning state and limits. No credentials.
`get_connection_strings`	A project's pooled (PgBouncer) and direct connection URLs. Output contains live credentials.
`create_ephemeral_database`	Create an ephemeral database - a throwaway Postgres with no account or login, destroyed after 72 hours unless claimed. Never starts the device login. Output contains the claim token, shown once.
`get_ephemeral_database`	An unclaimed ephemeral database's state, expiry and, once ready, connection URLs, by claim token. No authentication. Output contains live credentials.
`claim_ephemeral_database`	Keep an ephemeral database: attach it to your organization as a normal project, data and connection strings unchanged. Needs an account with an active plan.
`create_preview_database`	Create a preview (`empty` or `clone`, optional `ttl_hours`); poll the returned job with `get_job`.
`list_preview_databases`	A project's preview databases with state, source, and TTL expiry.
`delete_preview_database`	Permanently delete a preview and its role (async job). Not recoverable.
`reset_preview_database`	Reset a preview to its source state - `clone` re-clones production, `empty` wipes clean. Current preview data is lost (async job).
`extend_preview_ttl`	Set a preview's expiry to `ttl_hours` (1-168) from now - an absolute new TTL, not a delta added to the remaining time.
`get_preview_connection_strings`	A preview's pooled and direct connection URLs. Output contains live credentials.
`create_backup`	Queue an on-demand backup with an optional label (async job).
`list_backups`	Completed backups, including verification state.
`export_database`	Queue a logical export (`pg_dump` custom-format archive) of the project database (async job). Exports expire after 7 days.
`list_exports`	A project's exports, newest first, with state, size, and expiry.
`get_export_download`	A short-lived (15 minute) presigned download URL for a completed export.
`restore`	Restore a backup (`backup_key`), restore point (`restore_point_id`), or PITR timestamp (`restore_time`) into an existing or new preview. Optional `allow_unverified_backup`. Cannot overwrite the production database - that path needs explicit human confirmation and is dashboard/CLI only.
`import_preflight`	Synchronously check an external source Postgres database (size, version, extensions) against the project before importing. Changes nothing.
`import_database`	Import a live external Postgres database, overwriting the project's production database. Requires `confirm: true` (set only after the user explicitly approved); run `import_preflight` first. Dump-file imports need the CLI's `capydb import --file`.
`get_schema`	The complete database schema in one call: schemas, tables, views, columns, constraints, enums, extensions. Prefer over introspecting `pg_catalog` with `run_sql`. `preview_id` introspects a preview instead.
`generate_types`	Generate source code from the live schema: TypeScript interfaces (`style`: `capydb` or `supabase`), Zod schemas, or a Drizzle schema. Returns `{ filename, content }`; `preview_id` generates from a preview. See Type generation.
`list_restore_points`	Named restore points plus the project's PITR window.
`create_restore_point`	Pin an existing `backup_key` or a PITR timestamp before a risky change. For a fresh backup, run `create_backup`, wait, and select its key with `list_backups` first.
`delete_restore_point`	Retire a restore point once the change it guarded is verified; underlying backups follow normal retention.
`run_sql`	Run SQL against the live project database via the Studio runner (default 200 rows, max 1000, 15s timeout). Executes writes and DDL too; recorded in SQL history.
`list_tables`	Tables and views in the project database.
`get_table_rows`	Rows from a table (`schema`, `table`, optional `limit`).
`get_observability`	Live metrics snapshot: connections, size vs storage limit, active and slowest queries, derived alerts.
`get_job`	Poll an async job until `completed`/`failed`; failed jobs include the error.
`list_jobs`	A project's async jobs, newest first (default 25).
`list_extensions`	The extension allowlist with enabled/trusted state and installed versus available version per extension.
`enable_extension`	Enable an extension (async job). Extensions that load a shared library (`pg_cron`, `pgaudit`, `pg_qualstats`) restart the database, dropping open connections for a few seconds.
`disable_extension`	Disable an extension (async job). Runs `DROP EXTENSION` without `CASCADE`, so it fails with the dependency error rather than dropping dependent objects.
`update_extension`	Update an installed extension to the version the platform now provides. Extensions CapyDB manages itself are kept current automatically and are not updatable this way.
`suggest_indexes`	Index candidates derived from the predicates the project's queries actually filtered on, each costed as a hypothetical index - nothing is created and nothing is written. Needs `pg_qualstats` (and `hypopg` for size estimates).
`list_alerts`	Open alerts by default (capped at 50), with kind, severity, and observed versus limit values; `include_resolved` adds the last 30 days of history.
`acknowledge_alert`	Acknowledge an alert. Idempotent, and visual only - it does not silence notifications.
`get_logs`	A window of the project's database log stream, filterable by severity, with a cursor for resuming.
`major_upgrade_preflight`	Check whether the database can move to a Postgres major. Changes nothing, so it is safe to run repeatedly; extensions without a build for the target major are the usual blocker. Executing a major upgrade is operator-assisted and deliberately not exposed here.

Security

Use a project-scoped API key. The agent then can only touch the projects it needs; an org-wide key grants every project in the organization.
get_connection_strings and get_preview_connection_strings return URLs with embedded credentials, and they reach the model's context. Only enable this server with agents you trust, and rotate credentials if a key or URL leaks.
run_sql is not read-only. Point agents at preview databases for risky experimentation - previews are disposable and resettable by design.
The two destructive production paths are gated: import_database refuses to run without confirm: true, and restore only targets previews - production-overwrite restores are deliberately not exposed over MCP.

On this page