Quickstart

Add your database

Create a project and register your origin database in the dashboard, or use the CLI. projects create makes the project and its primary database in one atomic call, so pass the connection details inline:

# Authenticate the CLI with an API key from the dashboard
# (Settings > Account > API Keys, or Settings > Organization > API Keys).
# `pgbeam auth login` prompts you to paste the key, verifies it, and selects
# your organization automatically (you pick one if you belong to several).
pgbeam auth login
pgbeam projects create \
  --name my-project \
  --host db.example.com --port 5432 \
  --database app \
  --username app_user --password "$DB_PASSWORD" \
  --ssl-mode verify-full

PgBeam stores these credentials and uses them to reach your database upstream. The agent never receives them. To attach more databases later (for example a read replica), use pgbeam db add with --name <database> and its own --username/--password.

Create a read-only policy

A policy profile defines what the agent may do. Create a read-only one and note the pol_… id it prints; you'll attach the credential to it next.

pgbeam policies create --name read-only --mode read_only
# → Policy profile created: pol_1a2b3c…

Issue a scoped agent credential

Pass the policy id from the previous step to --policy:

pgbeam agents create --name analytics-bot --policy pol_1a2b3c…

This returns two things the agent can use:

# Scoped Postgres connection string
postgresql://agent_4f2c:****@a1b2c3.proxy.pgbeam.app:5432/app

# Hosted MCP endpoint (Bearer pba_…)
https://<project>.proxy.pgbeam.app/mcp

See Agent credentials for the full surface.

Connect the agent over MCP

agents create already printed a ready-to-paste config for your client (pass --client claude-desktop, cursor, vscode, cline, windsurf, or all to pick the host). For Claude Code it looks like this:

{
  "mcpServers": {
    "pgbeam": {
      "type": "http",
      "url": "https://<project>.proxy.pgbeam.app/mcp",
      "headers": { "Authorization": "Bearer pba_..." }
    }
  }
}

Need to regenerate it later (e.g. after rotating the token), or write it straight to the client's config file?

pgbeam agents mcp-config \
  --url https://<project>.proxy.pgbeam.app/mcp \
  --mcp-token pba_... \
  --client cursor --write

Claude Desktop, Cline, and Windsurf keep one config file per machine instead of one per project, so --write prints those with their per-OS path rather than overwriting a file that holds your other MCP servers. Claude Desktop also reaches a remote endpoint through an mcp-remote bridge. See Hosted MCP for each config and where its file lives.

The dashboard credential reveal renders the same blocks for Claude Code, Cursor, and VS Code. The agent now has eight tools: query, validate_sql, list_tables, describe_table, explain, and schema_catalog, every call enforced against the policy, plus search_docs and read_doc for looking up the PgBeam docs. Prefer a connection string? See Connection string.

Watch the audit log

Every statement the agent runs is recorded with its decision, rows, bytes, and latency. Open the Audit tab in the dashboard, or:

pgbeam audit list --credential agt_xxx

A read-only policy blocks writes and DDL automatically. The blocked statement never reaches your database, and the agent receives an LLM-readable reason.