Skip to content

docs(readme): add MCP Server feature section #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tianzhou merged 1 commit into from
Jun 25, 2026
Merged

docs(readme): add MCP Server feature section #24

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -110,6 +110,28 @@ Generate, explain, fix, and rewrite SQL with an AI assistant that understands yo
<img src="https://raw.githubusercontent.com/pgplex/pgconsole/main/docs/images/features/ai-assistant/ai-risk-assessment.webp" alt="AI risk assessment" />
</td></tr></table>

### MCP Server

Expose your Postgres connections to external AI agents (Claude, Cursor, IDEs, CI bots) over the [Model Context Protocol](https://modelcontextprotocol.io) — without handing out raw database credentials. Agents connect to a remote MCP endpoint and inherit the same IAM, permission, and audit controls as human users.

- **Remote & token-authenticated** — a Streamable HTTP endpoint at `/mcp`; each agent authenticates with `Authorization: Bearer <token>`
- **Two agent kinds** — a *pure* service account (authorized by `agent:<id>` IAM rules) or a *delegated* agent that acts on behalf of a user, optionally capped to fewer permissions or connections
- **Permission-shaped tools** — every agent can `list_connections`; catalog tools (`list_objects`, `describe_table`) appear once it has an accessible connection, and execution tools unlock per grant: `explain_query` (`explain`), `query` (`read`), `write_data` (`write`), `run_ddl` (`ddl`)
- **Same governance as the UI** — every statement runs through per-statement SQL permission detection, default-deny IAM, and the audit log
Comment on lines +118 to +120

@tianzhou tianzhou Jun 25, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, and technically correct: resolvePermissions short-circuits to all permissions when auth is disabled or no [[iam]] rules are defined (IAM is opt-in), so "default-deny" and "authorized by agent:<id> IAM rules" describe the model only once auth + IAM are active.

I've left the wording as-is for now because it deliberately mirrors the framing already used in the README's existing Database Access Control section ("Default deny — users have no access unless a rule explicitly grants it"), which likewise describes the active-IAM model rather than the auth-off/no-rules shortcut. Qualifying it only in the MCP section would make the two inconsistent.

If we want to surface the opt-in shortcut, the better fix is a one-liner in the Database Access Control section (the canonical place for it) rather than the MCP blurb — happy to do that in a follow-up if you'd like.


```toml
# A standalone agent, authorized via [[iam]] just like a user
[[agents]]
id = "ci-bot"
name = "CI Pipeline"
token = "generate-a-long-random-secret" # openssl rand -hex 32

[[iam]]
connection = "staging"
permissions = ["read", "ddl"]
members = ["agent:ci-bot"]
```

### Database Access Control

Fine-grained IAM controls who can read, write, or administer each connection. Permissions are enforced at the application layer — no database roles needed.
Expand Down
Loading