docs(readme): add MCP Server feature section

[tianzhou]

What

Adds an MCP Server entry to the README Features section (right after AI Assistant), documenting pgconsole's remote MCP server for external AI agents.

The section covers:

• Remote Streamable HTTP endpoint at /mcp with Authorization: Bearer <token> auth
• Pure (service-account, agent:<id> IAM) vs. delegated (on_behalf_of, with optional permission/connection caps) agents
• Permission-shaped tool surface — list_connections (always), catalog tools list_objects/describe_table (once a connection is accessible), and execution tools explain_query (explain), query (read), write_data (write), run_ddl (ddl)
• Same IAM + per-statement SQL permission detection + audit path as the UI
• An [[agents]] + [[iam]] config snippet

Why

The MCP server is a shipped capability (server/mcp.ts) but wasn't listed among the README features.

Verification

Wording was checked against server/mcp.ts, server/lib/config.ts, server/lib/iam.ts, and pgconsole.example.toml. Docs-only change — no code paths touched.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
pgconsole	Ready	Preview, Comment	Jun 25, 2026 11:12am

[greptile-apps]

Greptile Summary

This docs-only PR adds a MCP Server feature section to the README, documenting pgconsole's existing remote MCP endpoint (server/mcp.ts). The wording was cross-checked against the implementation and the example config, and all claims are accurate.

• Documents the Streamable HTTP /mcp endpoint with Authorization: Bearer <token> auth, two agent kinds (pure service account vs. delegated on-behalf-of), and the permission-gated tool surface (list_connections always; catalog tools per accessible connection; execution tools per IAM grant).
• Includes a minimal TOML config snippet that exactly mirrors the example in pgconsole.example.toml, giving readers a working starting point for a pure agent.

Confidence Score: 5/5

Documentation-only change with no code paths touched; all described behavior verified accurate against the implementation.

Every claim in the new section was traced to server/mcp.ts and pgconsole.example.toml and holds up: the endpoint path, auth scheme, two agent kinds, permission-gated tool surface, and the TOML snippet are all correct. No code is modified, so there is no regression risk.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Adds a new MCP Server feature section between AI Assistant and Database Access Control. All claims verified accurate against server/mcp.ts and pgconsole.example.toml: endpoint path, Bearer auth, two agent kinds (pure/delegated), permission-gated tool surface, and the TOML config snippet.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Agent as External AI Agent
    participant MCP as pgconsole /mcp
    participant IAM as IAM Layer
    participant SQL as SQL Permission Detector
    participant DB as Postgres
    participant Audit as Audit Log

    Agent->>MCP: POST /mcp Authorization Bearer token
    MCP->>MCP: Resolve agent by token
    alt Invalid or missing token
        MCP-->>Agent: 401 Unauthorized
    end

    MCP->>IAM: getAgentPermissions per connection
    IAM-->>MCP: Set of Permission per connection

    Agent->>MCP: ListTools request
    MCP->>MCP: selectToolNames based on permission union
    MCP-->>Agent: Filtered tool list

    Agent->>MCP: CallTool e.g. query or write_data or run_ddl
    MCP->>IAM: Re-check permission on specific connection
    MCP->>SQL: detectRequiredPermissions on SQL
    SQL-->>MCP: primaryPermissions and full permission set
    MCP->>MCP: Enforce expectedPerm matches primary
    MCP->>DB: Execute SQL
    DB-->>MCP: Result rows and row count
    MCP->>Audit: auditSQL with actor connection sql
    MCP-->>Agent: Tool result JSON

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Agent as External AI Agent
    participant MCP as pgconsole /mcp
    participant IAM as IAM Layer
    participant SQL as SQL Permission Detector
    participant DB as Postgres
    participant Audit as Audit Log

    Agent->>MCP: POST /mcp Authorization Bearer token
    MCP->>MCP: Resolve agent by token
    alt Invalid or missing token
        MCP-->>Agent: 401 Unauthorized
    end

    MCP->>IAM: getAgentPermissions per connection
    IAM-->>MCP: Set of Permission per connection

    Agent->>MCP: ListTools request
    MCP->>MCP: selectToolNames based on permission union
    MCP-->>Agent: Filtered tool list

    Agent->>MCP: CallTool e.g. query or write_data or run_ddl
    MCP->>IAM: Re-check permission on specific connection
    MCP->>SQL: detectRequiredPermissions on SQL
    SQL-->>MCP: primaryPermissions and full permission set
    MCP->>MCP: Enforce expectedPerm matches primary
    MCP->>DB: Execute SQL
    DB-->>MCP: Result rows and row count
    MCP->>Audit: auditSQL with actor connection sql
    MCP-->>Agent: Tool result JSON

Loading

_{Reviews (1): Last reviewed commit: "docs(readme): add MCP Server feature sec..." | Re-trigger Greptile}

[Copilot]

Pull request overview

Adds an MCP Server entry to the README Features section to document pgconsole’s remote MCP endpoint for external AI agents, including auth, agent types, tool surface, and an example [[agents]] / [[iam]] configuration snippet.

Changes:

• Documented the MCP server capability in the README Features list.
• Described agent authentication and the permission-shaped MCP tool surface.
• Added a TOML snippet showing how to configure a standalone agent and authorize it via IAM.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tianzhou]

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.