PostgreSQL REST API and MCP server

Supported PostgreSQL versions and hosts

• Versions: PostgreSQL 9.6, 10, 11, 12, 13, 14, 15, 16 and 17.
• Hosting: self-hosted or on-prem, Amazon RDS, Aurora, Supabase, Neon and Azure Database for PostgreSQL.
• Driver: pgx v5, pure Go, built into the single Faucet binary. Nothing else to install.

1. Connect PostgreSQL

npx @faucetdb/faucet serve

Open http://localhost:8080, go to Databases → Add database, pick PostgreSQL and fill in:

• Host and Port (5432 by default)
• Database, Username and Password. Special characters in the password need no escaping.
• SSL mode: leave Prefer for a local database; choose Require for RDS, Supabase, Neon and other hosted services.

Click Test connection. Faucet reports how many tables it found, or explains what went wrong, before anything is saved. Then click Add database; the API is live immediately.

From the command line, add the database before starting the server (a running server picks up CLI-added databases on its next start):

faucet db add --name mydb --driver postgres \
  --host db.example.com --user api --password-prompt --database mydb --ssl-mode require

# or paste the connection string from your provider
faucet db add --name mydb --driver postgres \
  --dsn "postgres://user:[email protected]:5432/mydb?sslmode=require"

Make sure the database accepts connections from the machine running Faucet (security groups or IP allow-lists on hosted services). To expose a schema other than public, set it with --schema or in the database’s access options.

2. Create a role and an API key

faucet role create --name reader --verbs GET --service mydb
faucet key create --role reader   # prints the key once

Roles grant GET, POST, PUT, PATCH and DELETE per database and per table. Anything a role doesn’t grant is denied.

3. Query PostgreSQL over REST

# List tables
curl "http://localhost:8080/api/v1/mydb/_table" -H "X-API-Key: faucet_YOUR_KEY"

# Read rows with a filter, chosen fields, sorting and pagination
curl "http://localhost:8080/api/v1/mydb/_table/orders?filter=status%20%3D%20'shipped'&fields=id,total&order=created_at%20DESC&limit=10&offset=0" \
  -H "X-API-Key: faucet_YOUR_KEY"

# Include the total count for pagination
curl "http://localhost:8080/api/v1/mydb/_table/orders?include_count=true&limit=10" \
  -H "X-API-Key: faucet_YOUR_KEY"

Filters read like a SQL WHERE clause, for example age > 21 AND status IN ('active', 'trial') or email IS NOT NULL, and every value is sent as a bound parameter. Responses wrap rows in a resource array.

With a role that allows writes, inserts return the new rows, including server-generated IDs and defaults, because Faucet uses PostgreSQL’s RETURNING. Updates and deletes require a filter or ids:

curl -X POST "http://localhost:8080/api/v1/mydb/_table/customers" \
  -H "X-API-Key: faucet_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"resource": [{"name": "Acme Corp", "email": "[email protected]"}]}'

curl -X PATCH "http://localhost:8080/api/v1/mydb/_table/customers?ids=42" \
  -H "X-API-Key: faucet_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}'

The full OpenAPI 3.1 spec is at /openapi.json; import it into Postman or a client generator.

4. Give AI agents the same database over MCP

The MCP endpoint runs on the same port. Connect an agent with a read-only key:

claude mcp add --transport http faucet http://localhost:8080/mcp \
  --header "X-API-Key: faucet_YOUR_KEY"

The agent can list tables, describe them and query rows, limited by the key’s role. Configs for Claude Desktop, Cursor, VS Code, Windsurf and ChatGPT are in the MCP docs and on the admin UI’s AI agents page.

What you get for PostgreSQL