How to connect Postgres to Claude (and make it work for your team)

#mcp #ai #claude #postgres

Connecting Postgres to Claude is easy. For one person. But when you want your whole team querying the same database, things fall apart. Here's what I've learned and built to manage this.

The quick way: direct MCP

Anthropic published a reference Postgres MCP server. Install it, point it at your database, and Claude can run queries in minutes.

// claude_desktop_config.json
{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres",
        "postgresql://read_user:pass@host:5432/mydb"
      ]
    }
  }
}

Once connected, Claude can list tables, inspect schemas, and run SQL. Ask "how many users signed up this week?" and it writes the query, runs it, and returns the answer. Fast, free, and useful for a solo dev exploring a schema they already know.

Tip: add context with Claude Projects
You can improve accuracy by creating a Claude Project, adding notes about your schema (table descriptions, metric definitions, business rules), and using that project when querying. This works well for one person, but the context lives in your Claude account and isn't shared with anyone else.

Important: use a read replica
Never point analytics queries at your production primary. A slow aggregation can lock tables and affect your app. RDS, Supabase, Neon, and most hosted Postgres providers offer read replicas.

Where it starts breaking

The direct connection works for one person. When you try to hand it to a team, two things break: reliability and management.

The reliability problem

Production Postgres schemas are messy. They evolve over years, with abbreviated column names, legacy tables, and implicit business logic. Claude sees this:

-- What Claude sees
usr_acct (id, sts, crt_at, upd_at, tier_id, ref_src, acq_ch)
ord (id, usr_id, amt_gross, amt_net, disc_cd, sts, crt_at)
sub (id, usr_id, plan_id, mrr_cents, churn_at, cancel_rsn)

Without context, Claude guesses. Is sts a status code or a string? Does amt_net include tax? What values of sts mean "completed"? Two people ask "what's our revenue?" and get two different numbers because Claude interprets it differently each time.

The context problem

You can work around the messy schema by adding notes in a Claude Project. But now you're maintaining context manually. When a column gets renamed, a table gets added, or a metric definition changes, someone has to update those notes. And if your teammate has their own project with their own notes, you're back to inconsistent answers.

The management problem

Everyone manages their own config. Each person edits a JSON file on their laptop with database credentials. Your head of ops isn't doing that.
Everyone gets the same access. There's one connection string. Everyone sees everything. Unless you create separate database users for each person, there's no way to restrict who sees what.
Credentials live on laptops. Database passwords in plaintext config files. No way to revoke access without changing the password for everyone.
Switching providers breaks everything. If you move from Supabase to Neon, or RDS to Railway, every person on the team needs to update their config.
No visibility. No audit log of what queries ran, who asked what, or whether the answers were correct.

The team-ready way: Claude + ContextFlo

ContextFlo connects to your Postgres database using read-only credentials. It scans your schema and auto-generates context: what every table and column actually means, how tables relate to each other, and how key metrics should be calculated.

Your team still asks questions in Claude. The difference is what Claude knows. Here's how it works:

Everyone on the team gets the same definitions. The connection is managed centrally. If you switch Postgres providers, you update one connection, not twenty laptops. Access controls scope which tables each person can query. Every question and every query is logged.

Works with any hosted Postgres: AWS RDS, Supabase, Neon, PlanetScale, Google Cloud SQL, Azure Postgres, Railway, Render, or self-hosted.

The natural path

	Start here	When you need a team
Setup	Edit JSON config per person	Connect once, invite team
Schema context	Raw table/column names	Auto-generated descriptions
Metric consistency	No	Shared definitions
Access control	Same DB user for everyone	Per-table, per-user ACL
Credentials	On every laptop	Centralized, never exposed
Provider change	Update every config	Update one connection
Audit trail	None	Full query log

Start with the direct MCP connection. It's the fastest way to see if Claude + Postgres is useful for your workflow. When you want to bring your team in, ContextFlo handles the context, governance, and visibility so you don't have to build it yourself.

Get started for free on Contextflo

Originally published on contextflo.com/blog/claude-with-postgres