MCP server

@capydb/mcp — let MCP-capable agents manage projects, previews, backups, extensions, 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, Postgres extensions, and SQL.

Every tool returns structured JSON; API failures surface as MCP tool errors carrying the control plane's error message. Tools that trigger asynchronous jobs either wait with a bounded poll (about 10 minutes) or hand you the job to poll with capydb_get_job.

Requires Node.js ≥ 22 and a CapyDB API key (capy_live_...), created in the dashboard under Organization → API keys.

Configuration

Environment variable	Required	Default	Description
`CAPYDB_API_KEY`	yes	—	Org or project-scoped API key
`CAPYDB_API_URL`	no	`https://capydb.dev/api/capydb`	Control-plane base URL

The key is read from the environment only — never written to disk or logged.

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

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
`capydb_list_projects`	List projects visible to the key (id, name, slug, region, plan, state). No credentials.
`capydb_get_project`	One project's full metadata: database/role names, ports, limits, latest job id. No credentials.
`capydb_get_connection`	Pooled/direct connection URLs for a project or preview. Output contains live credentials. Needs `credentials:read`.
`capydb_list_previews`	A project's preview/branch databases with mode, state, and TTL expiry.
`capydb_create_preview`	Create a preview (`clone` or `empty`, optional `ttl_hours`); waits for provisioning by default.
`capydb_delete_preview`	Delete a preview (async job).
`capydb_reset_preview`	Recreate a preview from its original source, discarding changes (async job).
`capydb_extend_preview`	Extend a preview's TTL by N hours.
`capydb_run_sql`	Run SQL via the Studio runner (default 200 rows, max 1000, 15s timeout). Executes writes and DDL too; recorded in SQL history.
`capydb_create_backup`	Trigger an on-demand backup with an optional label; `wait` to poll until done.
`capydb_list_backups`	Completed backups with label, size, and verification state.
`capydb_get_job`	Poll an async job until `completed`/`failed`; failed jobs include the error.
`capydb_list_extensions`	The project's extension allowlist with enabled/trusted per extension.
`capydb_enable_extension`	Enable an allowlisted extension (async job).

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.
capydb_get_connection returns 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.
capydb_run_sql is not read-only. Point agents at preview databases for risky experimentation — previews are disposable and resettable by design.

MCP server

On this page