MCP Client (Claude, Cursor, Windsurf, etc.)
    |
    | Streamable HTTP + OAuth 2.1
    v
Cloudflare Worker
    |-- OAuthProvider --> Cloudflare Access --> OIDC IdP (Okta, Authentik, Azure AD, ...)
    |-- McpAgent (Durable Object — one per authenticated session)
    |       |-- Role-based tool registration via IdP groups
    |       |-- SQL Safety Parser (blocks dangerous patterns)
    |       |-- Prompts (query assistant, schema explorer)
    |       |-- Resources (schema dump, health dashboard)
    |-- pg-client --> Hyperdrive --> PostgreSQL
                                        |
                            +-----------+-----------+
                            |                       |
                    Public databases         Private databases
                   (Neon, Supabase,        (via Cloudflare Tunnel
                    RDS, Cloud SQL)         + VPC Service)

git clone https://github.com/vnikhilbuddhavarapu/postgresql-mcp.git
cd postgresql-mcp
cp wrangler.jsonc.example wrangler.jsonc
npm install

wrangler kv namespace create OAUTH_KV

# For a publicly reachable database:
wrangler hyperdrive create pg-mcp \
  --connection-string="postgres://user:password@host:5432/dbname"

# For a private database via Cloudflare Tunnel:
# First create a VPC Service, then:
wrangler hyperdrive create pg-mcp \
  --connection-string="postgres://user:password@<PRIVATE_IP>:5432/dbname" \
  --vpc-id="<VPC_SERVICE_ID>"

cp .dev.vars.example .dev.vars
# Edit .dev.vars with your Access credentials

# Generate types
wrangler types

# Deploy
wrangler deploy

# Push secrets to production
wrangler secret bulk .dev.vars

https://<your-worker>.workers.dev/mcp

npx @modelcontextprotocol/inspector
# Enter your /mcp URL, authenticate via the OAuth flow

npm install          # Install dependencies
wrangler types       # Generate TypeScript types from bindings
npm run type-check   # TypeScript type checking
npm test             # Run Vitest unit tests (48 tests)
npm run lint         # Lint with oxlint
npm run format       # Format with oxfmt
wrangler dev         # Local development server (note: Hyperdrive requires deploy for full testing)
wrangler deploy      # Deploy to Cloudflare

postgresql-mcp/
├── src/
│   ├── index.ts                  # McpAgent (Durable Object) + OAuthProvider entry point
│   ├── env.d.ts                  # Environment type declarations
│   ├── auth/
│   │   ├── access-handler.ts     # OAuth /authorize + /callback flow with Cloudflare Access
│   │   └── workers-oauth-utils.ts # CSRF, PKCE, state management, token exchange
│   ├── db/
│   │   ├── pg-client.ts          # PostgreSQL client wrapper (Hyperdrive connection pooling)
│   │   ├── sql-parser.ts         # SQL classification and safety validation
│   │   └── schemas.ts            # Zod schemas for all tool inputs and database types
│   ├── tools/
│   │   ├── universal.ts          # 3 tools — userInfo, connectionInfo, healthCheck
│   │   ├── readonly.ts           # 7 tools — listTables, describeTable, executeQuery, ...
│   │   ├── readwrite.ts          # 5 tools — insertRows, updateRows, deleteRows, ...
│   │   └── admin.ts              # 10 tools — databaseHealth, createIndex, executeDDL, ...
│   ├── prompts/
│   │   ├── query-assistant.ts    # Natural language to SQL with live schema context
│   │   └── schema-explorer.ts    # Guided database exploration
│   └── resources/
│       ├── schema.ts             # schema://tables — full schema dump
│       └── health.ts             # health://overview — database health dashboard
├── tests/
│   └── sql-parser.test.ts        # 48 unit tests for SQL safety parser
├── .dev.vars.example             # Template for environment secrets
├── wrangler.jsonc.example        # Template for Worker configuration (copy to wrangler.jsonc)
├── tsconfig.json                 # TypeScript configuration
└── package.json                  # Dependencies and scripts