MCP server

zb-mcp is a Model Context Protocol server for the Databasezy public API. An assistant such as Claude Code, Cursor or Claude Desktop can list engines and plans, create, pause, resume and delete instances, get connection details and find documentation through the same org-scoped, role-checked /v1 API the portal and CLI use.

run

npx -y zb-mcp                      # stdio, what MCP clients spawn
npx -y zb-mcp --http --port 3333   # Streamable HTTP at http://127.0.0.1:3333/mcp

Node 22 or newer. The server logs to stderr only.

Authentication and scope

Variable	Purpose
ZB_API_KEY	Org-scoped API key (zb_...), sent as Authorization: Bearer. Create one with zb api-keys create or in the portal.
ZB_ORG_ID	Default organization. Every tool also accepts an org_id argument.
ZB_PROJECT_ID	Default project for create_instance; project_id per call overrides it.
ZB_API_URL, ZB_DOCS_URL	Override the API and docs base URLs (defaults https://api.databasezy.com, https://docs.databasezy.com).

The server adds no permissions: a key with the developer role and instances:read gives a read-only assistant; instances:write allows create, pause, resume and delete. Each call is an ordinary API request and appears in the audit log with the API key as the actor.

Client configuration

Claude Code

claude mcp add databasezy -e ZB_API_KEY=zb_... -e ZB_ORG_ID=org_... -e ZB_PROJECT_ID=prj_... -- npx -y zb-mcp

.mcp.json (Claude Code) · ~/.cursor/mcp.json (Cursor) · claude_desktop_config.json (Claude Desktop)

{
  "mcpServers": {
    "databasezy": {
      "command": "npx",
      "args": ["-y", "zb-mcp"],
      "env": { "ZB_API_KEY": "zb_...", "ZB_ORG_ID": "org_...", "ZB_PROJECT_ID": "prj_..." }
    }
  }
}

hosted endpoint (Streamable HTTP)

{
  "mcpServers": {
    "databasezy": {
      "url": "https://mcp.databasezy.com/mcp",
      "headers": { "Authorization": "Bearer zb_..." }
    }
  }
}

Tools

Tool	Maps to	Notes
list_engines	GET /v1/engines	Engine ids, wire protocol, versions, free-tier availability
list_plans	GET /v1/plans + /v1/sizes + /v1/regions	Quotas and included usage
list_sizes, list_regions	GET /v1/sizes, GET /v1/regions
list_instances	GET /v1/orgs/{org}/instances or .../projects/{project}/instances	Paged with limit and cursor
get_instance	GET /v1/orgs/{org}/instances/{id}	Status, endpoint host and port once running
create_instance	POST /v1/orgs/{org}/projects/{project}/instances	engine and size required; returns the instance and next steps
delete_instance	DELETE /v1/orgs/{org}/instances/{id}	Requires confirm: true; annotated destructive
pause_instance, resume_instance	POST .../actions/pause, .../actions/resume	409 on an invalid transition
get_connection_info	instance + engine catalogue	Host, port, wire, TLS note and a connection-string template with <username>/<password> placeholders
list_backups, create_backup	.../instances/{id}/backups	Not in API 1.0.0: returns a not-available error pointing at backups
get_usage	GET /v1/orgs/{org}/usage	Not in API 1.0.0: not-available error
list_migrations, create_migration	/v1/orgs/{org}/migrations	Not in API 1.0.0: not-available error
get_docs_url	this documentation site	Up to five matching pages for a topic

Resources: databasezy://engines, databasezy://plans (plans, sizes, regions), databasezy://instances and the template databasezy://instances/{id}. Prompts: provision-database (argument framework, for example prisma or django) and migrate-from-provider (argument provider, for example neon or rds), which produce step-by-step plans that reference the framework and migration guides.

Endpoints that ship later

The backups, usage and migrations tools check the OpenAPI document the server was built from. They return a structured not-available error today and start working as soon as the API publishes those endpoints and the package is regenerated; no change to the assistant’s configuration is needed.

What it never does

• No credentials. Reveal is a one-time, signed fetch from the cell (security) and is not exposed to the assistant. get_connection_info returns a template; a request with allow_credentials: true gets an explanation and a pointer to the portal or zb instances credentials reveal <id>.
• No silent destruction. delete_instance requires confirm: true and carries the MCP destructiveHint annotation so clients ask the human first. There is no restore-in-place or resize tool in this version.
• No cross-org access. Every request is scoped by the API key’s organization; ids from another org are 404.

Source

The package lives at services/mcp in the Databasezy repository and is published as zb-mcp on npm. Its API types are generated from services/api/openapi.json with openapi-typescript, and its docs index from this site.