quickstart.mdx

title	Quickstart
icon	Rocket
description	Connect an AI agent to your Postgres safely in two minutes. Issue a scoped credential, attach a read-only policy, and watch the audit log.

This guide gives an AI agent safe, read-only access to your database through PgBeam. The agent gets a scoped credential and a hosted MCP URL. It never sees your real database credentials, and you can revoke its access with one click.

You need a PostgreSQL database reachable from the internet and its connection details (host, port, user, password, database name). Sign up at [dash.pgbeam.com](https://dash.pgbeam.com) with email and password, or with Google, GitHub, or Vercel; new accounts start on a 14-day trial. To use the CLI, create an [API key](/docs/api-keys) under **Settings > Account > API Keys** (personal) or **Settings > Organization > API Keys** (organization) and authenticate with it (the CLI does not do browser sign-in). ### 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:

```bash title="Create a project with your database"
# 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.

```bash title="Create a read-only policy"
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`:

```bash title="Create an agent credential"
pgbeam agents create --name analytics-bot --policy pol_1a2b3c…
```

This returns two things the agent can use:

```bash
# 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](/docs/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:

```json title=".mcp.json"
{
  "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?

```bash title="Regenerate and write the config"
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](/docs/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](/docs/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:

```bash title="List the audit log"
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.

What to tighten next

The read-only policy is a safe default. Narrow it further as you go:

• Allowlists: restrict to the exact tables.
• Masking: hash or redact PII the agent should never read.
• Budgets: cap queries per window and rows per result.
• Kill-switch: cut an agent off mid-session.