Setting Up a PostgreSQL MCP Server in VS Code (AWS RDS, Aurora & On-Prem)

The Model Context Protocol (MCP) lets AI coding assistants talk to external systems — including your databases — through a standard interface. Once a PostgreSQL MCP server is wired into VS Code, GitHub Copilot's agent mode can inspect schemas, run queries, analyze execution plans, and help with tuning, all in natural language against a live database.

This guide walks through configuring a PostgreSQL MCP server in VS Code that works against AWS RDS for PostgreSQL, Aurora PostgreSQL, and on-premises PostgreSQL. It applies to PostgreSQL versions 10 through the current release.

---

Prerequisites

Before starting, make sure you have:

• VS Code 1.102 or later. Native MCP support (agent mode plus mcp.json) has been generally available since 1.102.
• GitHub Copilot and Copilot Chat, signed in, with agent mode enabled. Agent mode is the MCP client inside VS Code — this is where MCP tools are surfaced.
• A runtime for the server: either Python 3.12+ or Docker. You only need one; details are below.
• Network reachability from your workstation to each database on the PostgreSQL port (default 5432). For cloud databases this usually means the security group allows your IP — and, for instances in a private subnet, a VPN, bastion, or Direct Connect path.
• A database user for the MCP server. Use a least-privilege, read-only account for anything pointed at production.
• psql (optional but recommended) for a quick connectivity test before wiring up MCP.

---

Step 1 — Choose an MCP server

Two things to know before you pick:

• The original reference server, @modelcontextprotocol/server-postgres, was deprecated in 2025 after a SQL-injection vulnerability was found. Avoid it — its read-only mode is not a safe boundary.
• The maintained, feature-rich choice is Postgres MCP Pro (crystaldba/postgres-mcp). It adds capabilities that matter for real database work: read-only and restricted execution modes, EXPLAIN plan analysis, index-tuning recommendations, and database health checks (bloat, cache-hit ratios, vacuum, replication lag). It is written in Python.

The rest of this guide uses Postgres MCP Pro.

---

Step 2 — Install the runtime and the server

Option A — pipx (recommended)

Postgres MCP Pro is a Python application, so it needs Python 3.12+. On Windows, install Python with winget:

powershell

winget install Python.Python.3.13

Then install the server with pipx (this puts a postgres-mcp executable on your PATH):

powershell

pip install pipx
pipx ensurepath
pipx install postgres-mcp

Reopen the terminal and verify:

powershell

python --version      # 3.12 or higher
postgres-mcp --help   # confirms the server is installed and on PATH

Option B — Docker

If you'd rather not install Python, pull the image instead:

bash

docker pull crystaldba/postgres-mcp

You'll reference docker as the command in mcp.json (shown in Step 4).

---

Step 3 — Prepare the database connection

The MCP server connects using a standard PostgreSQL connection URI. Get the connection working with psql first — it is much easier to debug connectivity here than through the MCP layer.

Connection string formats

On-premises PostgreSQL:

postgresql://USER:PASSWORD@HOST:5432/DBNAME

Add ?sslmode=require if the server is configured for SSL.

AWS RDS for PostgreSQL (SSL strongly recommended):

postgresql://USER:PASSWORD@your-instance.xxxxx.<region>.rds.amazonaws.com:5432/DBNAME?sslmode=verify-full&sslrootcert=/path/to/global-bundle.pem

Aurora PostgreSQL:

postgresql://USER:PASSWORD@your-cluster.cluster-xxxxx.<region>.rds.amazonaws.com:5432/DBNAME?sslmode=verify-full&sslrootcert=/path/to/global-bundle.pem

Notes on the cloud options:

• SSL. Download the AWS RDS combined CA bundle (global-bundle.pem) once and point sslrootcert at it. sslmode=verify-full validates the server certificate; use sslmode=require if you only need encryption without certificate verification.
• Aurora endpoints. Use the cluster (writer) endpoint if the tool needs to write. Use the reader endpoint (...cluster-ro-xxxxx...) for query and analysis work — it stays off the writer and is read-only at the database level, which is a safer default.

Test the connection

bash

psql "postgresql://USER:PASSWORD@HOST:5432/DBNAME?sslmode=require"

If psql connects, the MCP server will too.

---

Step 4 — Configure the server in VS Code

VS Code reads MCP server definitions from an mcp.json file. Place it in a workspace as .vscode/mcp.json so it applies to that project, or open your user-level config from the Command Palette: MCP: Open User Configuration.

Two important details:

1. VS Code uses the top-level key servers — not mcpServers. Configuration examples written for other clients (Claude Desktop, Cursor, Cline) often use mcpServers; paste those verbatim and VS Code will silently ignore them.
2. Keep credentials out of the file. Use an inputs block with a promptString so VS Code prompts for the connection URI (masked) at runtime instead of storing a password in plain text.

Complete example using the pipx-installed server:

json

{
  "inputs": [
    {
      "id": "pg-uri",
      "type": "promptString",
      "description": "PostgreSQL connection URI",
      "password": true
    }
  ],
  "servers": {
    "postgres": {
      "type": "stdio",
      "command": "postgres-mcp",
      "args": ["--access-mode=restricted"],
      "env": { "DATABASE_URI": "${input:pg-uri}" }
    }
  }
}

--access-mode=restricted limits the server to read-only transactions with resource limits — the right default for production. Switch to --access-mode=unrestricted only on databases where you intend to allow writes and schema changes.

Docker variant — if you installed with Docker, replace the server entry:

json

"servers": {
  "postgres": {
    "type": "stdio",
    "command": "docker",
    "args": ["run", "-i", "--rm", "-e", "DATABASE_URI", "crystaldba/postgres-mcp", "--access-mode=restricted"],
    "env": { "DATABASE_URI": "${input:pg-uri}" }
  }
}

Connecting to more than one database? Add one entry per database under servers (for example pg-onprem, pg-rds, pg-aurora), each with its own input, so you can query them side by side.

Windows note: if VS Code can't launch postgres-mcp, run where postgres-mcp and put the full path to the .exe in the command field.

---

Step 5 — Start and verify

1. Reload VS Code: Command Palette → Developer: Reload Window.
2. Command Palette → MCP: List Servers, start your server, then choose Show Output to watch the startup log. Connection and authentication errors show up here.
3. Open Copilot Chat, switch to agent mode, and confirm the Postgres tools appear.
4. Try a prompt such as "list the schemas in this database" or ask for a database health check.

---

Easier alternative: the Microsoft PostgreSQL extension

If you'd prefer a GUI and no hand-written mcp.json, Microsoft publishes an official PostgreSQL extension for VS Code with a built-in AI/MCP surface. Install it from the Extensions view (published by Microsoft), add a database connection, then right-click the database in the Connections tree and choose Connect AI to start an agent-mode session — or use the @pgsql chat participant in Copilot Chat.

It is excellent for schema browsing, query authoring, and general management, and it has a read-only access-mode setting. For deeper tuning work (hypothetical-index analysis, detailed health checks), Postgres MCP Pro is stronger. The two are not mutually exclusive — a common setup is the extension as a daily driver, plus the standalone server when you need its tuning tools.

---

Security checklist

• Use a least-privilege database account for the MCP server — read-only for anything touching production. The account's grants are your real safety boundary.
• Run in restricted access mode unless you specifically need writes.
• Never store passwords in mcp.json. The inputs / promptString pattern keeps them out of the file and out of source control.
• Enforce SSL on cloud databases with sslmode=verify-full and the CA bundle.
• Optional tuning extensions: index-tuning and slow-query features rely on pg_stat_statements (enabled via the parameter group / shared_preload_libraries) and hypopg for hypothetical indexes. Both are available on RDS and Aurora; install them on-prem. Basic querying and health checks work without them.

---

A note on PostgreSQL versions

The PostgreSQL driver used by the server works across a wide range of server versions — comfortably from PostgreSQL 10 through the current major release, and newer majors once their client libraries ship. Very old versions (such as 10, which is past end-of-life) still connect, though production databases should stay on supported releases.