Quickstart

Add your database

Create a project and add your origin database in the dashboard, or use the CLI:

pgbeam auth login
pgbeam projects create --name my-project
pgbeam db add --host db.example.com --port 5432 --database app --ssl-mode verify-full

PgBeam stores these credentials and uses them to reach your database upstream. The agent never receives them.

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 cursor, --client vscode, or --client all to pick the host). For Claude Code it looks like this:

{
  "mcpServers": {
    "pgbeam": {
      "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

The dashboard credential reveal renders the same blocks. The agent now has query, list_tables, describe_table, and explain tools, every call enforced against the policy. 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.