Faz Docs

Install faz, add a Postgres database, connect Claude Desktop, and run your first safe query — in five steps.

This is the fastest path from "never seen faz" to "Claude is querying my database with safety checks." It uses Postgres as the example database and Claude Desktop as the example AI client; the substitutions for other databases and clients are linked at each step.

If you'd rather just install without the full setup, use Install.

What you'll do

Install faz with pip.
Generate a faz.yaml config.
Add your Postgres connection.
Wire faz into Claude Desktop.
Restart Claude and ask it about your data.

Total time: under five minutes if Postgres is already running.

Prerequisites

Python 3.10+.
A Postgres instance you can read from — local or remote, with credentials. For a quick local one: docker run -p 5432:5432 -e POSTGRES_PASSWORD=test -d postgres:16.
Claude Desktop installed and signed in. (Cursor, Claude Code, or any MCP client works the same way; see Integrations.)

The walkthrough

Install faz.

pip install faz-core

This installs the faz CLI plus all 14 database connector dependencies. It takes 30–90 seconds. Examples below use faz <cmd>; if you installed with uv or faz isn't on your PATH, see Install for the substitution.

Generate a starter config.

faz init

uv run faz init

python -m faz init

You'll see:

wrote /your/cwd/faz.yaml
created /your/cwd/.faz/

Next steps:
  1. Edit faz.yaml — replace the sample database with your real connection
  2. Tighten the `permissions` block to match your trust model
  3. `faz serve` to start the REST API on :8787
  4. `faz mcp install` to wire Claude Desktop / Cursor

The directory now has faz.yaml (your config) and .faz/ (where the audit log will live).

Add your database. Open faz.yaml and replace the sample databases: entry with your real connection. For our example Postgres:

faz.yaml

databases:
  - name: <database>          # used as --database <database> in queries
    type: postgresql
    host: localhost
    port: 5432
    database: <db-name>       # the Postgres database to connect to
    username: <username>
    password: <password>      # literal value; env interpolation isn't implemented yet

permissions:
  - database: <database>      # must match `name:` above
    access: R                 # read-only baseline; no agent can write

safety:
  max_rows_per_query: 1000
  query_timeout_seconds: 30

Confirm it parses:

faz policy

uv run faz policy

python -m faz policy

You should see:

<database>
    baseline: R

safety:
    max_rows_per_query     =  1000
    query_timeout_seconds  =  30

If you'd rather not edit YAML, run faz add-database for an interactive wizard that walks you through one connection at a time.

Wire faz into Claude Desktop.

faz mcp install --target claude

uv run faz mcp install --target claude

python -m faz mcp install --target claude

This writes the MCP server entry to Claude Desktop's config file (path varies by OS — macOS uses ~/Library/Application Support/Claude/claude_desktop_config.json, Linux uses ~/.config/Claude/claude_desktop_config.json, Windows uses %APPDATA%\Claude\claude_desktop_config.json).

To preview without writing the file:

faz mcp install --target claude --dry-run

uv run faz mcp install --target claude --dry-run

python -m faz mcp install --target claude --dry-run

For Cursor, Claude Code, or OpenClaw, swap the --target value (cursor, claude is also Claude Code, openclaw). For any other MCP client, see Generic MCP.

Restart Claude Desktop and ask it about your data.

Claude only re-reads its MCP config on startup. Quit fully (not just close the window) and relaunch.

In a new chat, ask:

What databases do you have access to?

Claude calls faz's list_databases tool and replies with the connector name (your <database> from faz.yaml) plus its discovered tables.

Then ask something concrete:

How many rows are in pg_class?

Claude generates and submits SELECT COUNT(*) FROM pg_class. faz runs it through the safety pipeline (Prompt Guard, RBAC, AST, Injection, Guardrails — see How faz protects you), executes it, and returns the count.

Every query lands in .faz/audit.jsonl. Tail it in another terminal:

faz logs --follow

uv run faz logs --follow

python -m faz logs --follow

Did a step fail? See MCP not loading if Claude doesn't pick up faz, Connection failed for database errors, or Query blocked if a specific query gets rejected.

What you just set up

One Postgres connection under the name you set, read-only.
The MCP integration — Claude Desktop now talks to faz on stdio whenever it needs to query your databases.
An audit trail — every query Claude submits, allowed or blocked, lands in .faz/audit.jsonl.

faz isn't running a long-lived server; the MCP integration spawns a faz mcp process per Claude session. To use the REST API instead — for scripts, CI, or non-MCP clients — start faz serve and point at port 8787. The pipeline and audit log are identical.

Quickstart

What you'll do

Prerequisites

The walkthrough

What you just set up

Next steps

How faz protects you

Configuration

Connect another client

On this page