---
title: "Quickstart"
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."
canonical: "https://pgbeam.com/docs/quickstart"
last-updated: "2026-09-14T19:37:21.000Z"
---

# Quickstart

> 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.

URL: https://pgbeam.com/docs/quickstart

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 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 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:

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.

## Issue a scoped agent credential

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

This returns two things the agent can use:

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:

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

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
ten tools: `briefing`, `query`, `validate_sql`, `list_tables`,
`describe_table`, `explain`, `schema_catalog`, and `my_permissions`, 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:

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.