pREST v2.1.0 lets Cursor, Claude Desktop or curl run permission-aware SELECT queries on your PostgreSQL. Agents get read-only tools capped at 100 rows per call, behind pREST’s existing auth and ACL.
The MCP server runs at /_mcp on the same HTTP port as the REST API, with no separate MCP process. This tutorial covers Docker setup, a curl walkthrough and client wiring. It requires v2.1.0+. See the v2.0.0 / v2.1.0 release overview for context.
pREST v2 series: Architecture (rc6) → v2.0.0 / v2.1.0 GA → This post (MCP tutorial) → AI plugins
Table of Contents
- What pREST MCP gives your agents
- When to use pREST MCP vs direct database access
- Step 1: start Postgres and pREST
- Step 2: learn the endpoint and its tools
- Step 3: walk through it with curl
- Step 4: turn on auth
- Step 5: connect Cursor
- Step 6: connect Claude Desktop
- Step 7: try these agent prompts
- How to call it from any HTTP client
- What agents can’t do through it
- How to fix common errors
- FAQ
- Also from Insurgency Labs
- Links
What pREST MCP gives your agents
Model Context Protocol (MCP) is the open standard AI agents use to discover and call tools. pREST’s /_mcp endpoint implements MCP as read-only HTTP JSON-RPC on the existing REST server. It uses the same port, the same auth middleware and the same database routing.
Agents call tools/list to discover tables and tools/call to run schema-aware SELECT queries. That’s safer than handing agents a raw Postgres connection string. pREST enforces access.tables ACL, caps row counts and logs requests through the HTTP layer.
When to use pREST MCP vs direct database access
| Scenario | Use pREST MCP | Use direct DB access |
|---|---|---|
| Agent exploration in Cursor or Claude | Yes — ACL-scoped, read-only | Risky — full SQL, no HTTP audit trail |
| Production writes or migrations | No — MCP is read-only in v2.1.0 | Yes |
| Multi-tenant routing via aliases | Yes — inherits registry routing | Requires per-tenant connection management |
| Ad-hoc SQL outside pREST permissions | No | Yes — if you accept the security tradeoff |
| Audit trail via HTTP auth (JWT/basic) | Yes | Depends on DB-level logging |
Step 1: start Postgres and pREST
You need:
- pREST v2.1.0+. Run
docker pull prest/prest:v2.1.0or build from prest/prest. - PostgreSQL with at least one table pREST can expose.
- A
prest.tomlwhoseaccess.tablespermissions grantreadon the tables agents should query. - Optionally, JWT or basic auth. This tutorial shows unauthenticated local dev first, then auth.
The fastest path is the repo’s integration stack. For a minimal local setup:
# Postgres
docker run -d --name prest-pg \
-e POSTGRES_PASSWORD=postgres \
-e POSTGRES_DB=prest-test \
-p 5432:5432 postgres:16
# Create a test table
docker exec prest-pg psql -U postgres -d prest-test -c \
"CREATE TABLE IF NOT EXISTS public.test (id serial PRIMARY KEY, name text); \
INSERT INTO public.test (name) VALUES ('prest tester') ON CONFLICT DO NOTHING;"
# pREST v2.1.0 (adjust config mount as needed)
docker run -d --name prestd \
--link prest-pg:postgres \
-p 3000:3000 \
-e PREST_PG_HOST=postgres \
-e PREST_PG_USER=postgres \
-e PREST_PG_PASS=postgres \
-e PREST_PG_DATABASE=prest-test \
prest/prest:v2.1.0
Make sure your prest.toml grants read access:
[[access.tables]]
name = "test"
schema = "public"
permissions = ["read"]
For a full multi-service setup, see docker-compose-test.yml in the pREST repo.
Check that the server is up:
curl -s http://localhost:3000/_health
curl -s http://localhost:3000/_mcp | head -c 200
Step 2: learn the endpoint and its tools
pREST serves MCP on the same server as catalog, CRUD and script routes:
| Method | Path | Purpose |
|---|---|---|
GET |
/_mcp |
Discovery payload — server metadata and available tools |
POST |
/_mcp |
JSON-RPC 2.0 requests |
It supports three RPC methods:
initializeruns the handshake.tools/listenumerates tools, including per-table selects.tools/callexecutes a tool.
The protocol version is 0.1. Each select call returns at most 100 rows.
These are the tools:
| Tool | Purpose |
|---|---|
prest.list_databases |
List databases or registered aliases |
prest.list_schemas |
List schemas in a database |
prest.list_tables |
List tables in a schema |
prest.describe_table |
Column metadata and typed input schema |
prest.select_table |
Generic table read |
prest.select.{database}.{schema}.{table} |
Per-table tool with column-aware filters |
Schema-aware table tools take typed arguments: columns, filters, order_by, limit and offset. order_by takes a field, or -field for descending. In multi-database mode, tool generation expands across registered aliases.
Step 3: walk through it with curl
1. Discovery
curl -s http://localhost:3000/_mcp | jq .
Expected output: prest server name, protocol version, and a tools array.
2. Initialize
curl -s http://localhost:3000/_mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize"}' | jq .
Expected output: JSON-RPC result with server info and capabilities.
3. List tools
curl -s http://localhost:3000/_mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | jq '.result.tools[].name'
Expected output: prest.list_databases, prest.describe_table, and generated prest.select.* tools for permitted tables.
4. Describe a table
curl -s http://localhost:3000/_mcp \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "prest.describe_table",
"arguments": {
"database": "prest-test",
"schema": "public",
"table": "test"
}
}
}' | jq .
Expected output: column names and types for the test table.
5. Select with projection, filter, and ordering
curl -s http://localhost:3000/_mcp \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "prest.select.prest-test.public.test",
"arguments": {
"columns": ["id", "name"],
"filters": {"name": "prest tester"},
"order_by": ["id"],
"limit": 5,
"offset": 0
}
}
}' | jq .
Expected output: matching rows as JSON in the tool result.
Step 4: turn on auth
When auth.enabled = true in config, /_mcp requires the same credentials as other protected routes.
With basic auth:
curl -s -u myuser:mypass http://localhost:3000/_mcp \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
With JWT:
curl -s http://localhost:3000/_mcp \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer YOUR_JWT_TOKEN' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
For local development, auth can stay disabled. Misconfigured JWT settings disable auth with warning logs instead of blocking startup (PR #974). Don’t rely on that in production.
Step 5: connect Cursor MCP to PostgreSQL via pREST
Cursor launches stdio MCP servers. Install the official prest-mcp adapter:
brew install prest/tap/prest-mcp
Then add it to .cursor/mcp.json in your project root:
{
"mcpServers": {
"prest": {
"command": "prest-mcp",
"env": {
"PREST_MCP_URL": "http://localhost:3000/_mcp"
}
}
}
}
When auth is enabled, add PREST_MCP_TOKEN:
{
"mcpServers": {
"prest": {
"command": "prest-mcp",
"env": {
"PREST_MCP_URL": "https://api.example.com/_mcp",
"PREST_MCP_TOKEN": "your-jwt-here"
}
}
}
}
Some Cursor versions also support URL-based MCP ("url": "http://localhost:3000/_mcp"). The stdio adapter is the recommended path per docs.prestd.com/ai. For Cursor rules and skills, see the pREST for Cursor plugin.
Then:
- Verify
curl -s http://localhost:3000/_mcp | headreturns JSON with"name": "prest". - Save
mcp.json. - Restart Cursor.
- Open the MCP tools panel.
prest.list_tables,prest.describe_tableand per-table select tools should appear. - Try a prompt from the example agent prompts below.
Step 6: connect Claude Desktop to PostgreSQL via pREST
Claude Desktop expects stdio MCP servers. Use the official prest-mcp adapter:
brew install prest/tap/prest-mcp
{
"mcpServers": {
"prest": {
"command": "prest-mcp",
"env": {
"PREST_MCP_URL": "http://localhost:3000/_mcp"
}
}
}
}
When auth is enabled, add PREST_MCP_TOKEN to the env block. If prest-mcp isn’t on PATH, set "command" to the absolute binary path. See Install pREST MCP Adapter for Go and Docker options.
Step 7: try these agent prompts
After connecting MCP in Cursor or Claude, try these copy-paste prompts:
- List tables: “Use the prest MCP tools to list all tables in the public schema of prest-test.”
- Describe columns: “Use prest.describe_table to show columns and types for public.test.”
- Filter rows: “Use prest.select.prest-test.public.test to find rows where name equals ‘prest tester’. Return id and name only.”
- Compare schemas: “Use prest MCP to list tables in public and any other schemas you can see, and compare row counts where possible.”
How to call it from any HTTP client
Any client that can POST JSON-RPC works. Here’s a minimal Python example:
import requests
resp = requests.post(
"http://localhost:3000/_mcp",
json={"jsonrpc": "2.0", "id": 1, "method": "tools/list"},
)
for tool in resp.json()["result"]["tools"]:
print(tool["name"])
Other options:
- Postman: POST with a JSON body, using the same payloads as the curl examples above.
- Custom agents: loop
tools/list→tools/callin your orchestration code.
The curl walkthrough in this post is the reference implementation for all HTTP clients.
What agents can’t do through it
pREST MCP is read-only by design in v2.1.0:
- There are no insert, update or delete tools.
- Unsupported tool names return
400 Bad Request. - Existing identifier validation and ACL apply. Agents only see tables your
access.tablesrules permit. - A select call returns at most 100 rows.
- Multi-database mode generates tools per registered alias. Permissions are evaluated per alias and schema.
Auth and ACL stay in the HTTP middleware stack. The MCP layer doesn’t reimplement security.
How to fix common errors
| Symptom | Fix |
|---|---|
401 on /_mcp |
Add basic auth (-u) or Authorization: Bearer header; or disable auth for local dev |
| Empty or missing tools | Check access.tables grants read on the tables you expect |
400 on tool call |
Verify database, schema, and table match your alias and physical names |
| Tool not found | Run tools/list and copy the exact generated name (e.g. prest.select.prest-test.public.test) |
| Connection refused | Confirm pREST is listening on port 3000 and Postgres is reachable |
Check pREST logs for permission denials and config warnings.
For how /_mcp compares with the other Postgres MCP servers, see Postgres MCP servers compared. It covers crystaldba, Supabase, Neon, pgEdge and the archived reference server. New to pREST? Start with pREST in 10 minutes.
FAQ
What is pREST’s MCP server?
It’s a read-only HTTP endpoint at /_mcp, introduced in v2.1.0. It exposes JSON-RPC methods for catalog discovery and schema-aware table reads. It reuses pREST’s existing authentication, database routing and access control.
How do I query PostgreSQL from Cursor using MCP?
Install prest-mcp (brew install prest/tap/prest-mcp). Add a stdio MCP server entry in .cursor/mcp.json with PREST_MCP_URL pointing to http://your-host:3000/_mcp. Set PREST_MCP_TOKEN if auth is enabled, then restart Cursor and check that the tools appear in the MCP panel.
Is pREST MCP read-only?
Yes. v2.1.0 MCP tools support discovery and SELECT operations only. There are no insert, update or delete tools. Unsupported operations return 400 Bad Request.
Does pREST MCP work with Claude Desktop?
Yes. Claude Desktop expects stdio MCP servers. Install prest-mcp and configure it with PREST_MCP_URL pointing to your pREST /_mcp endpoint. Add PREST_MCP_TOKEN when auth is enabled.
What is the difference between pREST MCP and PostgREST?
PostgREST exposes PostgreSQL over REST but doesn’t ship an MCP endpoint. pREST v2.1.0 adds read-only MCP tools on the same server as its REST API, with ACL-scoped table selects for agents. Both are Postgres REST layers. pREST targets Go teams that need registry routing and agent integration.
Why use pREST MCP instead of giving agents a database connection string?
A connection string grants full SQL access with no HTTP-level ACL and no row caps. It also skips pREST’s auth middleware. MCP through pREST limits agents to read-only, permission-scoped tools with a 100-row cap per query.
Also from Insurgency Labs
Engineering leaders using Cursor or Claude to explore databases via pREST MCP may also want read-only delivery metrics from GitHub. DeliveryCompass shows EMs PR cycle time and review patterns without write access to your repos. See the DeliveryCompass overview. It’s free during Early Access. It isn’t a Jira replacement and doesn’t measure deploy-based DORA.