Verifying the Connection

After wiring up an integration, three quick checks confirm that faz is reachable and sees the right databases. Run them in order; each one only matters if the previous one passed.

If a check fails, the linked troubleshooting page has the next steps.

1. Confirm faz itself works

Before involving any client, make sure faz can read faz.yaml and connect to your databases.

faz policy

uv run faz policy

python -m faz policy

Expected output: a non-empty permission tree, grouped by database. If you see (no permissions loaded — check faz.yaml), the YAML didn't parse — fix that first. Common issues are documented on Connection failed.

Then:

faz test

uv run faz test

python -m faz test

Runs four probes per configured database (reachable, read, write, DDL) and prints ✓ / ✗. A clean install with one read-only Postgres looks like:

✓ list_databases — 1 configured

Per-DB safety probes  (1 configured)
  <database> (postgresql)  — policy: R
    ✓ reachable — 18 tables
    ✓ read on '<table>' (allowed) — allowed
    ✓ write blocked (target=faz_synthetic_does_not_exist) — at RBAC_GATE
    ✓ DDL blocked (target=faz_synthetic_does_not_exist) — at RBAC_GATE

  4/4 probes passed.

If reachable is ✗, faz couldn't open the connection. See Connection failed.

2. Confirm the MCP path (for MCP clients)

Quickest test: ask the assistant directly.

What databases do you have access to?

If the assistant replies with the right databases — the same names that appeared in faz policy — the MCP wire-up works. You're done.

If the assistant says it doesn't have any databases, or doesn't know what faz is, or claims it can't reach external tools, the client probably doesn't know about faz. See MCP not loading.

For deeper inspection, find the MCP log file for your client:

• Claude Desktop (macOS): ~/Library/Logs/Claude/mcp-server-faz.log
• Claude Desktop (Linux): ~/.config/Claude/logs/mcp-server-faz.log
• Claude Desktop (Windows): %APPDATA%\Claude\logs\mcp-server-faz.log
• Cursor: Settings → Output → MCP, or ~/.cursor/logs/
• OpenClaw: ~/.openclaw/logs/mcp.log
• Claude Code: stderr from the CLI session, plus ~/.claude/logs/ if your version writes them.

You should see a line like faz mcp: server started (or equivalent) at session start. If you see Python tracebacks, faz crashed on launch — the most common cause is FAZ_CONFIG pointing at a path that doesn't exist or doesn't parse.

3. Confirm the REST path (for HTTP clients)

If you're using faz serve rather than MCP:

curl http://localhost:8787/v1/health

Expected:

{ "status": "ok", "version": "0.1.0", "databases_connected": 1 }

If databases_connected is 0, the HTTP server is running but no connectors initialised successfully. Check the faz serve stdout for connector startup errors.

Then:

curl http://localhost:8787/v1/databases | jq '.databases[] | {name, reachable, error}'

Each database shows reachable: true or reachable: false. Failed ones include the underlying connection error in error.

A live end-to-end check:

curl -X POST http://localhost:8787/v1/query/simple \
  -H 'Content-Type: application/json' \
  -d '{
    "database": "<database>",
    "table": "<table>",
    "query": "SELECT 1 AS ping"
  }' | jq .status

Should print "ok". If it prints "blocked", your permissions: block is denying the read — see Permissions.

What "verified" means

After all three checks pass:

• faz reads faz.yaml, knows about your databases, and can connect to them.
• Your client (MCP or HTTP) can spawn or reach faz.
• The four MCP tools (or six REST endpoints) are callable.
• The safety pipeline runs on every query.

You can now use the assistant or your custom client. Anything that breaks beyond this point is at the query level — wrong table name, blocked by a permission, blocked by an injection check — not at the wire-up level.

Related

• Connection failed — when faz can't reach a database.
• MCP not loading — when an MCP client can't find faz.
• Query blocked — when a query reaches faz but is rejected.
• Audit log — see exactly what was attempted, by whom, and what happened.