Architecture

PGSandbox MCP is a thin MCP server in front of one or more reachable Postgres admin connections. It does not install or manage Postgres versions itself.

Flow

Agent / MCP client
        |
        v
PGSandbox MCP
        |
        v
Configured Postgres profile
        |
        v
Task-specific databases and roles

Resource model

Each experiment gets one database, one login role, credentials scoped to that database, a TTL, and optional labels for task, repo, branch, or agent.

Profiles

Profiles support multiple Postgres versions or hosts without changing the MCP contract.

{
  "defaultProfile": "local-pg17",
  "profiles": [
    { "name": "local-pg17", "adminUrl": "postgres://postgres:postgres@localhost:5432/postgres" },
    { "name": "local-pg16", "adminUrl": "postgres://postgres:postgres@localhost:5433/postgres" }
  ]
}

Cleanup

Cleanup can run via the explicit cleanup_expired MCP tool or a scheduled process. It only deletes databases listed in the metadata table and matching the configured prefix.