Postgres MCP Pro for Windsurf: Setup & Config

What you can do with Postgres MCP Pro in Windsurf

Pick PostgreSQL tooling that goes beyond queries into health checks, plans, and index evaluation.

• Investigate slow queries with execution plans and statistics.
• Review database health using a restricted read-only connection.

Before you start: Postgres MCP Pro in Windsurf

• Python 3.12+ for this launch path
• uv with uvx
• PostgreSQL database access credentials
• An MCP-compatible client

The README supports this restricted replacement for its unrestricted example. pg_stat_statements and hypopg are optional database extensions needed for fuller performance and index analysis. Docker is also documented.

Postgres MCP Pro Windsurf configuration

1. Choose Windsurf configuration scope

   For Postgres MCP Pro, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add Postgres MCP Pro to Windsurf

   Use the postgres-mcp entry below in mcpServers. Keep Postgres MCP Pro's documented stdio connection fields and your other Windsurf entries.

3. Check Postgres MCP Pro in Windsurf

   Postgres MCP Pro: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "uvx",
      "args": [
        "postgres-mcp",
        "--access-mode=restricted"
      ],
      "env": {
        "DATABASE_URI": "<PostgreSQL connection URI with your database credentials>"
      }
    }
  }
}

Postgres MCP Pro tools available to Windsurf

Postgres MCP Pro's stored tool list documents 9 tools; compare it with Windsurf's connected tool list, because the stored list is not a live check.

list_schemas

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for list_schemas.

Discover schemas available in the PostgreSQL instance.

list_objects

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for list_objects.

Inspect tables, views, sequences, and extensions within a schema.

get_object_details

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for get_object_details.

execute_sql

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for execute_sql.

explain_query

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for explain_query.

Inspect a query plan and optionally evaluate hypothetical indexes.

get_top_queries

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for get_top_queries.

analyze_workload_indexes

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for analyze_workload_indexes.

analyze_query_indexes

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for analyze_query_indexes.

Recommend indexes for a supplied set of up to ten SQL queries.

analyze_db_health

After refreshing Postgres MCP Pro in Windsurf settings, check Cascade's tool list for analyze_db_health.

Check cache, connections, indexes, constraints, sequences, and vacuum health.

Postgres MCP Pro: full stored tool descriptions

Troubleshooting Postgres MCP Pro in Windsurf

• Check uvx postgres-mcp (from uv, for Python tools) on the machine running Windsurf's MCP integration for Postgres MCP Pro; refresh MCP and inspect Cascade's tools.
• Check DATABASE_URI for Postgres MCP Pro; do not bypass a Windsurf permission error with a broad administrator token.
• Postgres MCP Pro uses stdio here: Windsurf must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Advanced workload and index analysis needs optional Postgres extensions.
• Known limitation: Unrestricted mode allows data and schema modification.
• Known limitation: Native Python execution requires Python 3.12 or newer.
• General Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions