Metadata-Version: 2.5
Name: awslabs.postgres-mcp-server
Version: 1.2.4
Summary: An AWS Labs Model Context Protocol (MCP) server for postgres
Project-URL: homepage, https://awslabs.github.io/mcp/
Project-URL: docs, https://awslabs.github.io/mcp/servers/postgres-mcp-server/
Project-URL: documentation, https://awslabs.github.io/mcp/servers/postgres-mcp-server/
Project-URL: repository, https://github.com/awslabs/mcp.git
Project-URL: changelog, https://github.com/awslabs/mcp/blob/main/src/postgres-mcp-server/CHANGELOG.md
Author: Amazon Web Services
Author-email: AWSLabs MCP <203918161+awslabs-mcp@users.noreply.github.com>, Ken Zhang <kennthhz@amazon.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Requires-Dist: aiorwlock
Requires-Dist: boto3>=1.42.79
Requires-Dist: botocore>=1.42.79
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp[cli]<3.0.0,>=2.0.0
Requires-Dist: pglast<9,>=8.4
Requires-Dist: psycopg[binary,pool]>=3.1.12
Requires-Dist: pydantic>=2.10.6
Description-Content-Type: text/markdown

# AWS Labs postgres MCP Server

An AWS Labs Model Context Protocol (MCP) server for Aurora Postgres

## Features

### Natural language to Postgres SQL query

- Converting human-readable questions and commands into structured Postgres-compatible SQL queries and executing them against the configured Aurora Postgres database.

## Prerequisites

1. Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) or the [GitHub README](https://github.com/astral-sh/uv#installation)
2. Install Python using `uv python install 3.10`
3. This MCP server can only be run locally on the same host as your LLM client.
4. Docker runtime
5. Set up AWS credentials with access to AWS services
   - You need an AWS account with appropriate permissions
   - Configure AWS credentials with `aws configure` or environment variables

## Installation

| Kiro | Cursor | VS Code |
|:----:|:------:|:-------:|
| [![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=awslabs.postgres-mcp-server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.postgres-mcp-server%40latest%22%2C%22--connection-string%22%2C%22postgresql%3A//%5Busername%5D%3A%5Bpassword%5D%40%5Bhost%5D%3A%5Bport%5D/%5Bdatabase%5D%22%5D%2C%22env%22%3A%7B%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%7D%7D) | [![Install MCP Server](https://cursor.com/deeplink/mcp-install-light.svg)](https://cursor.com/en/install-mcp?name=awslabs.postgres-mcp-server&config=eyJjb21tYW5kIjoidXZ4IGF3c2xhYnMucG9zdGdyZXMtbWNwLXNlcnZlckBsYXRlc3QgLS1jb25uZWN0aW9uLXN0cmluZyBwb3N0Z3Jlc3FsOi8vW3VzZXJuYW1lXTpbcGFzc3dvcmRdQFtob3N0XTpbcG9ydF0vW2RhdGFiYXNlXSIsImVudiI6eyJGQVNUTUNQX0xPR19MRVZFTCI6IkVSUk9SIn0sImRpc2FibGVkIjpmYWxzZSwiYXV0b0FwcHJvdmUiOltdLCJ0cmFuc3BvcnRUeXBlIjoic3RkaW8iLCJhdXRvU3RhcnQiOnRydWV9) | [![Install on VS Code](https://img.shields.io/badge/Install_on-VS_Code-FF9900?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=PostgreSQL%20MCP%20Server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22awslabs.postgres-mcp-server%40latest%22%2C%22--connection-string%22%2C%22postgresql%3A%2F%2F%5Busername%5D%3A%5Bpassword%5D%40%5Bhost%5D%3A%5Bport%5D%2F%5Bdatabase%5D%22%5D%2C%22env%22%3A%7B%22FASTMCP_LOG_LEVEL%22%3A%22ERROR%22%7D%2C%22disabled%22%3Afalse%2C%22autoApprove%22%3A%5B%5D%2C%22transportType%22%3A%22stdio%22%2C%22autoStart%22%3Atrue%7D) |

Configure the MCP server in your MCP client configuration (e.g., for Kiro, edit `~/.kiro/settings/mcp.json`):

```json
{
  "mcpServers": {
    "awslabs.postgres-mcp-server": {
      "command": "uvx",
      "args": [
        "awslabs.postgres-mcp-server@latest",
        "--allow_write_query"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### Windows Installation

For Windows users, the MCP server configuration format is slightly different:

```json
{
  "mcpServers": {
    "awslabs.postgres-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.postgres-mcp-server@latest",
        "awslabs.postgres-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}
```

### Build and install docker image locally on the same host of your LLM client

1. 'git clone https://github.com/awslabs/mcp.git'
2. Go to sub-directory 'src/postgres-mcp-server/'
3. Run 'docker build -t awslabs/postgres-mcp-server:latest .'

### Add or update your LLM client's config with following:

#### Option 1: Using RDS Data API Connection (for Aurora Postgres)

```json
{
  "mcpServers": {
    "awslabs.postgres-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "AWS_ACCESS_KEY_ID=[your data]",
        "-e", "AWS_SECRET_ACCESS_KEY=[your data]",
        "-e", "AWS_REGION=[your data]",
        "awslabs/postgres-mcp-server:latest",
        "--allow_write_query"
      ]
    }
  }
}
```

NOTE: the MCP config example include --allow_write_query illustrate how to enable write queries. If you want to disable write queries, remove --allow_write_query option.

## Support for Database Cluster Creation

You can use the following LLM prompt to create a new Aurora PostgreSQL cluster:

> Create an Aurora PostgreSQL cluster named 'mycluster' in us-west-2 region

---

## Connection Methods

The MCP server supports connecting to multiple database endpoints using different connection methods via LLM prompts.

### Database Types
- **APG**: Amazon Aurora PostgreSQL
- **RPG**: Amazon RDS for PostgreSQL

### Example Prompts

**Connect using RDS Data API:**
> Connect to database named postgres in Aurora PostgreSQL cluster 'my-cluster' with database_type as APG, using rdsapi as connection method in us-west-2 region

**Connect using pgwire (Aurora PostgreSQL):**
> Connect to database named postgres with database endpoint as my-apg17-instance-1.ctgfg6yyo9df.us-west-2.rds.amazonaws.com with database_type as APG, using pgwire as connection method in us-west-2 region

**Connect using pgwire (RDS PostgreSQL):**
> Connect to database named postgres with database endpoint as test-apg17-instance-1.ctgfg6yyo9df.us-west-2.rds.amazonaws.com with database_type as RPG, using pgwire as connection method in us-west-2 region

---

### Supported Connection Methods

| Method | Description | Supported Database Types |
|--------|-------------|--------------------------|
| `pgwire` | Connect to PostgreSQL instance directly using the PostgreSQL wire protocol. Requires proper VPC security group configuration for direct database connectivity. | APG, RPG |
| `pgwire_iam` | Same as `pgwire`, but uses IAM authentication. Requires IAM authentication to be enabled on the Aurora PostgreSQL cluster. | APG only |
| `rdsapi` | Connect to Aurora PostgreSQL using the RDS Data API. Requires the RDS Data API to be enabled on the cluster. | APG only |

### Prerequisites by Connection Method

#### pgwire / pgwire_iam
- VPC security group must allow inbound connections from your MCP server to the database
- For `pgwire_iam`: IAM authentication must be enabled on the Aurora PostgreSQL cluster

#### rdsapi
- RDS Data API must be enabled on the Aurora PostgreSQL cluster
- Appropriate IAM permissions for Data API access

#### RDS Proxy auto-detection (opt-in)

The server can check whether an RDS Proxy fronts the target and route the connection through the proxy when a usable one is found. This applies to standalone RDS PostgreSQL instances (`RPG`) and to Aurora PostgreSQL clusters (`APG`).

**This is opt-in.** Pass `--rds_proxy auto` to enable it; the default is `off`, which connects directly exactly as before. The `connect_to_database` tool also accepts an optional `rds_proxy` parameter (`off` or `auto`) that overrides the startup setting for a single connection, since the MCP config file is not the only way connections are made.

It defaults to off because routing through a proxy can turn a working direct connection into a failure. A proxy that fronts your instance is not necessarily one this server can use:

- The proxy only accepts users whose secrets are registered in its `Auth` configuration. A proxy created for a different consumer may not register the secret this server authenticates with.
- Each `Auth` entry sets `IAMAuth` to `DISABLED`, `ENABLED`, or `REQUIRED`. A `pgwire` (password) connection is refused by an entry with `IAMAuth=REQUIRED`, and a `pgwire_iam` connection is refused by `IAMAuth=DISABLED`.
- For `pgwire_iam`, the `rds-db:connect` policy must authorize the *proxy* resource (`arn:aws:rds-db:<region>:<account>:dbuser:prx-<proxy-resource-id>/<db-user>`), not the instance. A policy scoped only to the instance will fail to authenticate through the proxy.
- The proxy may be unreachable from a host that can reach the instance, since it has its own subnets and security groups.

When `--rds_proxy auto` is set, the server checks the proxy's `Auth` configuration against the connection method and secret in use, and **skips an incompatible proxy** — logging why — rather than attempting a connection that would be rejected. It also requires the proxy's target for the instance to be healthy (`TargetHealth.State == AVAILABLE`), since an `available` proxy can have an unusable target.

For **Aurora clusters** there is one extra consideration. A proxy fronts the *cluster*, and
its default endpoint is read/write — read-only traffic needs a separate proxy endpoint with
`TargetRole=READ_ONLY`. So the endpoint is chosen to match what you asked for:

| You connect to | Routed to |
|---|---|
| Cluster writer endpoint (or no endpoint at all) | The proxy's default endpoint |
| Cluster reader endpoint | A `READ_ONLY` proxy endpoint, if one is available; otherwise direct |
| A custom endpoint, or a specific member instance endpoint | Always direct |

The last row is a limitation of proxies rather than a choice: a proxy selects its own backend,
so it cannot be asked for one specific member. Routing those through the proxy would silently
connect somewhere else. Likewise, a read-only request is only proxied when the cluster has a
healthy reader behind the proxy — otherwise reads would be served by the writer.

The lookup itself is best-effort: if the IAM permissions below are missing or the API call fails, the server logs a warning and connects directly. Results are cached briefly per target, so repeated connects do not re-query.

IAM permissions required for `--rds_proxy auto`:
- `rds:DescribeDBProxies`
- `rds:DescribeDBProxyTargets`
- `rds:DescribeDBProxyEndpoints` (Aurora read-only routing only)

Routing is transparent: **keep using the instance endpoint**. Detecting a proxy
changes where the server opens its socket, not how you address the target. The
instance endpoint remains the target's identity everywhere it matters — it keys
the per-target `--secret_arn` override map, it keys the internal connection
cache, and it is what `connect_to_database` echoes back as `db_endpoint`. So
subsequent `run_query` calls pass the same endpoint they always did.

When a proxy is in use, `connect_to_database` adds a `proxy_endpoint` field. The
key is absent entirely for a direct connection, so its presence answers "is this
proxied?":

```json
{
  "connection_method": "pgwire",
  "cluster_identifier": "",
  "db_endpoint": "myinstance.abc123.us-east-1.rds.amazonaws.com",
  "proxy_endpoint": "myproxy.proxy-abc123.us-east-1.rds.amazonaws.com",
  "database": "postgres",
  "port": 5432
}
```

That field is observability only — it is not a handle for the connection;
`db_endpoint` is. `get_database_connection_info` reports it too.

Two details worth knowing:

- **`pgwire_iam` tokens are issued for the proxy hostname**, which is what RDS Proxy
  IAM authentication requires, and why the `rds-db:connect` policy must name the
  `prx-*` resource as noted above.
- **The proxy is dialed on port 5432**, not the instance's port. RDS Proxy for
  PostgreSQL always listens on the engine default and exposes no port field to
  read, so the port moves with the host. The `port` reported in the response
  remains the instance's own, since it is part of the target's identity.

TLS is unaffected in principle — the proxy presents an RDS-issued certificate for
its own hostname, which the bundled CA set verifies under the default
`--sslmode=verify-full`.

### AWS Authentication

The MCP server needs AWS credential to read database cluster or instance data, and to to create clusters or instances. These are control plane operations that are separate from Postgres operations (i.e. SELECT, CREATE etc). If you choose to use rdsapi connection method, the AWS credential must have the rds-data:ExecuteStatement permission on the Aurora cluster (see https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonrdsdataapi.html). The MCP uses the AWS profile specified in the `AWS_PROFILE` environment variable. If not provided, it defaults to the "default" profile in your AWS configuration file.

```json
"env": {
  "AWS_PROFILE": "your-aws-profile"
}
```

Make sure the AWS profile has permissions to access the [RDS data API](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api.access), and the secret from AWS Secrets Manager. The MCP server creates a boto3 session using the specified profile to authenticate with AWS services. Your AWS IAM credentials remain on your local machine and are strictly used for accessing AWS services.

### Postgres Authentication

The MCP server supports IAM and username/password methods for Postgres authentication. You must use AWS secret manager to store the credential and to specify the --secretManagerARN in MCP configuration file.


### Security Consideration

#### `--allow_write_query` read-only enforcement is best effort

When the MCP server runs without `--allow_write_query`, it enforces a
**semantic read-only** policy. Each query is parsed with
[`pglast`](https://github.com/lelit/pglast) (libpg_query — PostgreSQL's own
parser). Only read statement shapes (`SELECT`/`WITH … SELECT`/`VALUES`/`TABLE`/
`SHOW`/`EXPLAIN` of a read) are allowed, and known functions whose requested
purpose is to mutate sequence, session, statistics, WAL, replication, catalog,
large-object, or index state are also rejected even when written as
`SELECT function(...)`.

“Read-only” describes the requested operation, not every internal effect of
executing it. An ordinary `SELECT` remains a read even though PostgreSQL updates
usage statistics, warms caches, takes snapshots, and acquires transient locks as
bookkeeping. By contrast, `nextval()` intentionally advances a sequence,
`pg_stat_statements_reset()` intentionally destroys statistics,
`pg_switch_wal()` intentionally changes WAL state, and
`brin_summarize_new_values()` persistently updates an index; those are writes.
Representative boundaries:

| Example | Read-only verdict | Why |
|---|---|---|
| ordinary `SELECT`, calculations, `random()`, `clock_timestamp()`, current-XID readers | allow | observes/calculates; engine bookkeeping (including XID assignment) is incidental |
| `currval()` / `lastval()` / `pg_stat_clear_snapshot()` | allow | observes or refreshes the caller's read snapshot without durable mutation |
| `pg_prewarm()` | allow | cache-only performance hint; no durable/logical state |
| replication-slot `peek` / statistics readers | allow | observes without consuming/resetting state |
| `nextval()` / `setval()` | reject | changes sequence state |
| `pg_stat_reset*()` / `pg_stat_statements_reset()` | reject | resets collected statistics |
| WAL, backup, replication-slot/origin management | reject | changes administrative/replication state |
| BRIN/GIN maintenance and large-object writes | reject | persists index or database data |
| `cron.schedule()` / `cron.unschedule()` | reject | changes scheduled-job metadata |

Regardless of mode, a dangerous set is always rejected — command execution
(`COPY … TO/FROM PROGRAM`), host filesystem access (`COPY … TO/FROM '<file>'`,
`pg_read_file`, `lo_import`, the `pg_ls_dir` and `adminpack` families),
SSRF/exfiltration (`dblink`, `aws_lambda.invoke`, `aws_s3.query_export_to_s3`),
DoS/corruption/severe server control (`pg_sleep`, backend termination, advisory
lock acquisition, recovery control, `pg_surgery`, buffer-cache eviction), and
settings that disable data-access controls (`row_security`,
`session_replication_role`) and bulk session resets (`RESET ALL`, `DISCARD ALL`)
that can restore weaker role/database defaults.
Multi-statement input is rejected, and the guard fails closed on parse errors.

Because the guard uses PostgreSQL's own parser, syntactic evasions that defeat
text matching — quoted identifiers, comments, and Unicode-escaped identifiers
(`U&"pg_read_fil\0065"`) — are decoded and classified exactly as the database
would, so they no longer bypass it.

**Treat this as a best-effort, defense-in-depth mechanism, not a security
boundary.** The known-function inventory is versioned to PostgreSQL core through
PG18 plus selected PostgreSQL-supplied/common RDS extensions; it is not a
complete extension firewall. A parser cannot infer that an arbitrary
user-defined or third-party function writes internally, resolve an overloaded
operator/function under a custom `search_path`, or inspect dynamic SQL. Built-in
operators are calculations/observations; a user-defined operator can invoke any
function and remains role-controlled. In write mode, `DO`/`CREATE FUNCTION`
bodies and run-time `EXECUTE` strings are opaque too. Always combine the guard
with the least-privilege role below.

#### TLS is enforced on direct (PG Wire) connections

For direct PostgreSQL connections (the psycopg / PG Wire path, used for IAM auth
and Secrets Manager password auth), the server connects with
`sslmode=verify-full`. This requires TLS — there is no silent plaintext
downgrade — and verifies both that the server certificate chains to a trusted CA
and that its hostname matches, so a credential is never sent in the clear and a
man-in-the-middle presenting a spoofed certificate is rejected. (The RDS Data
API path already runs over verified HTTPS.)

Aurora / RDS PostgreSQL endpoints present certificates from two different Amazon
PKIs, and this server trusts both out of the box:

- **Amazon RDS private CAs** (`rds-ca-rsa2048-g1` / `rds-ca-rsa4096-g1` /
  `rds-ca-ecc384-g1`) — used by direct DB instance / cluster endpoints. See
  [Using SSL/TLS to encrypt a connection to a DB cluster](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/UsingWithRDS.SSL.html).
- **Public Amazon Trust Services roots** (`Amazon Root CA 1`–`4`) — used by
  endpoints whose certificate is issued by AWS Certificate Manager (ACM), such
  as RDS Proxy and Aurora Serverless v1.

The package ships the union of both as a single combined bundle (assembled at
build time), so `verify-full` works against any of these endpoints without extra
configuration.

The connection is **always encrypted** — plaintext modes are not offered, so a
credential is never sent in the clear. What you can tune is how much of the
server's identity is verified, via `--sslmode`:

| `--sslmode` | Encrypted | Verifies CA chain | Verifies hostname | Typical use |
|---|---|---|---|---|
| `verify-full` (default) | yes | yes | yes | Aurora/RDS via its endpoint (direct instance, cluster, or RDS Proxy); self-hosted with a proper cert + matching hostname |
| `verify-ca` | yes | yes | no | tunnel / bastion / IP / `localhost` / CNAME where the hostname won't match the cert |
| `require` | yes | no | no | self-signed cert you don't want to validate; encrypt-only on a trusted network |

Certificate verification (the `verify-*` modes) needs a trusted CA. The combined
Amazon bundle described above is used by default. Select a different trust anchor
with `--ca_bundle`:

```
--ca_bundle /path/to/private-ca.pem   # e.g. self-hosted PostgreSQL with a private CA
--ca_bundle system                    # use the OS trust store (e.g. a publicly-trusted cert)
```

Self-signed / private-CA notes:

- **Self-signed or private CA:** use `--sslmode verify-ca --ca_bundle <cert.pem>`
  (validates the cert against your CA; skips the hostname check that a
  self-signed cert usually can't satisfy). `verify-full` also works only if the
  cert's hostname matches what you connect to.
- **Don't want to manage a cert file:** use `--sslmode require` (encrypted, no
  verification; `--ca_bundle` is ignored).

Because credentials are never sent in cleartext, a server that offers no TLS
will fail to connect under any mode. Enable TLS on the server (there is
intentionally no plaintext option).

#### Best practice: run the MCP server as a minimal-privilege Postgres role

The strongest control is to connect the MCP server using a dedicated Postgres
role that has only the privileges it actually needs, so that the database itself
enforces the boundary regardless of what SQL reaches it. In particular:

- **Do not** connect as a superuser, `rds_superuser`, or the cluster master user.
  Those roles bypass row-level security, can read credential catalogs
  (`pg_authid`, `pg_user_mappings`), and can terminate other sessions.
- **Do not** grant the connected role the predefined roles
  `pg_read_server_files`, `pg_write_server_files`, or `pg_execute_server_program`.
  These are what make host filesystem access and `COPY … TO/FROM PROGRAM`
  command execution possible; without them, the database refuses those operations
  even if a query reaches it.
- **Do not** grant the connected role `USAGE` on foreign-data wrappers or
  foreign servers (`GRANT USAGE ON FOREIGN DATA WRAPPER …` / `ON FOREIGN SERVER
  …`), and do not let it own them. Those privileges are what let a session reach
  an operator-chosen network endpoint: a read of a foreign table looks like an
  ordinary `SELECT` to any SQL filter, so the database's privilege check is the
  control. `postgres_fdw` grants no `USAGE` to non-owners by default — keep it
  that way.
- For read-only use, grant only `CONNECT` + `USAGE` + `SELECT` on the schemas the
  agent needs, and force read-only transactions at the role level.
- For read/write use, grant only the specific `INSERT`/`UPDATE`/`DELETE`
  privileges required, scoped to the necessary schemas and tables.

Combining a minimal-privilege role (database-enforced) with the blocklist
(application-enforced) gives you defense in depth: even if a query slips past the
blocklist, the role's privileges still bound what it can do.

The following is an example read-only role:

```sql
-- Create a read-only role for Postgres MCP server
CREATE ROLE postgres_mcp_server_readonly WITH LOGIN PASSWORD 'change-me'
    NOSUPERUSER NOCREATEDB NOCREATEROLE NOREPLICATION;

-- Allow connection and schema visibility for public schema
-- TODO: add additional schema if required
GRANT CONNECT ON DATABASE mydb TO postgres_mcp_server_readonly;
GRANT USAGE ON SCHEMA public TO postgres_mcp_server_readonly;

-- Read existing tables and sequences for public schema
-- TODO: add additional schema if required
GRANT SELECT ON ALL TABLES IN SCHEMA public TO postgres_mcp_server_readonly;
GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO postgres_mcp_server_readonly;

-- Read future tables and sequences for public schema
-- TODO: add additional schema if required
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON TABLES TO postgres_mcp_server_readonly;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT ON SEQUENCES TO postgres_mcp_server_readonly;

-- Force read-only transactions
ALTER ROLE postgres_mcp_server_readonly SET default_transaction_read_only = on;
```

#### Least-privilege guardrail (`--privilege_check`)

To make the guidance above hard to get wrong, the server validates the
connected role when a connection is established (at startup and via the
`connect_to_database` tool) and can refuse to operate as an over-privileged
role — a superuser, a member of `rds_superuser`, or a role with the
`BYPASSRLS` attribute (which defeats row-level security without being a
superuser). This is a guardrail, not the security boundary itself — the
database-enforced role privileges remain the real control — but it helps
prevent the MCP server from silently running with privileges that would
render the blocklist and RLS moot.

The behavior is controlled by the `--privilege_check` argument:

| Value | Behavior |
|-------|----------|
| `warn` (default) | Log a warning but allow a connection whose role is over-privileged (superuser, `rds_superuser` member, or `BYPASSRLS`). A connectivity/authentication failure still aborts (the guardrail only relaxes the *privilege* check, not the need for a working connection). |
| `enforce` | Reject the connection if the role is over-privileged (superuser, `rds_superuser` member, or `BYPASSRLS`). If the check cannot be performed, the connection is rejected (fail-closed). |
| `off` | Skip the privilege check entirely (connectivity is still verified). |

The default is `warn` so that upgrades, and the `create_cluster` bootstrap
(which necessarily connects as the `rds_superuser` master before any
least-privilege role exists), do not fail — the over-privileged connection is
allowed but a warning is logged. **For production, set `--privilege_check
enforce`** and connect with a dedicated least-privilege role such as the
read-only role above. Under `enforce`, a violation aborts the server at
startup and returns a connection failure through `connect_to_database`.

The check reads only the connected role's own entry in the `pg_roles` catalog
and tolerates clusters where `rds_superuser` does not exist (e.g. self-hosted
PostgreSQL). Note that on Amazon Aurora the master user is a *member of*
`rds_superuser` (rather than a raw `rolsuper` superuser), and the guardrail
detects that membership.

Example (add to the `args` array in your MCP config — recommended for
production):

```json
"args": [
  "awslabs.postgres-mcp-server@latest",
  "--privilege_check", "enforce"
]
```
