How to Use pREST's MCP Server — Query PostgreSQL from Cursor, Claude, or curl

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

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.0 or build from prest/prest.
  • PostgreSQL with at least one table pREST can expose.
  • A prest.toml whose access.tables permissions grant read on 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:

  • initialize runs the handshake.
  • tools/list enumerates tools, including per-table selects.
  • tools/call executes 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:

  1. Verify curl -s http://localhost:3000/_mcp | head returns JSON with "name": "prest".
  2. Save mcp.json.
  3. Restart Cursor.
  4. Open the MCP tools panel. prest.list_tables, prest.describe_table and per-table select tools should appear.
  5. 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:

  1. List tables: “Use the prest MCP tools to list all tables in the public schema of prest-test.”
  2. Describe columns: “Use prest.describe_table to show columns and types for public.test.”
  3. Filter rows: “Use prest.select.prest-test.public.test to find rows where name equals ‘prest tester’. Return id and name only.”
  4. 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/call in 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.tables rules 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.