MCP Database Access for Cursor IDE

This document explains how to use the postgres-mcp servers configured for the Heatwave project in Cursor IDE.

See also: MCP Servers Setup Guide for complete setup instructions including Google Analytics, AppSignal, and Claude Desktop configuration.

Overview

The project uses postgres-mcp to allow the AI assistant in Cursor to query databases directly. Four database connections are available:

Server Database Access Configuration
postgres-dev Local development Read/Write User ~/.cursor/mcp.json
postgres-production Production heatwave READ-ONLY User ~/.cursor/mcp.json
postgres-replica Replica heatwave READ-ONLY User ~/.cursor/mcp.json
postgres-versions Production audit trail READ-ONLY User ~/.cursor/mcp.json

Production Infrastructure

Server Hostname Public IP Tailscale IP Role
heatwave-db4 Primary 45.63.79.22 100.65.0.14 Read/Write (app connections)
heatwave-db3 Replica 66.42.114.16 100.68.87.143 Streaming replica

Setup

Prerequisites

  1. Docker Desktop - Must be running
  2. 1Password CLI - For production/replica access 
    brew install --cask 1password-cli
op signin
  3. jq - For JSON manipulation 
    brew install jq

All Databases (One-time Setup)

Run the setup script to configure all database connections in your personal Cursor config:

./script/setup_mcp_servers.sh

This is also called automatically by bin/setup when 1Password CLI is signed in.

This script:

  1. Configures postgres-dev for local Docker database (read/write)
  2. Reads production/replica connection strings from 1Password (IT/heatwave-prod-db)
  3. Writes all configurations to ~/.cursor/mcp.json
  4. Preserves any existing MCP server configurations

Restart Cursor after running the script.

1Password Item Setup

The setup script expects an item named heatwave-prod-db in the IT vault with these fields:

Field Value
connection-string postgres://user:pass@100.65.0.14:5432/heatwave?options=-c%20default_transaction_read_only%3Don
connection-string-replica postgres://user:pass@100.68.87.143:5432/heatwave?options=-c%20default_transaction_read_only%3Don
database_versions heatwave_versions (audit trail database name)

Important: Both connection strings must include the read-only option:

?options=-c%20default_transaction_read_only%3Don

Usage

After setup, you can ask the AI assistant to query databases:

Development Database

"Show me the largest tables in the dev database"
"Query orders created today"

Production Database (READ-ONLY)

"Check production for orders in the last hour"
"Show active users count from production"

Replica Database (READ-ONLY)

"Run an expensive analytical query on the replica"
"Check replication lag on postgres-replica"

Versions/Audit Database (READ-ONLY)

"Show recent changes to orders from the versions database"
"Query audit trail for user modifications"

Docker Container Names

When MCP servers are running, you'll see these containers in Docker Desktop:

Container Purpose
postgres-mcp-dev Local development
postgres-mcp-prod Production primary
postgres-mcp-replica Production replica
postgres-mcp-versions Audit trail database

Troubleshooting

MCP servers not loading

  1. Ensure Docker Desktop is running
  2. Restart Cursor completely (not just reload window)
  3. Check Docker logs: docker logs postgres-mcp-prod

"Not signed in to 1Password"

op signin

Updating credentials

Re-run the setup script:

./script/setup_mcp_servers.sh

Checking your configuration

# Project config (dev only)
cat .cursor/mcp.json

# Personal config (production/replica)
cat ~/.cursor/mcp.json

Security Considerations

  1. Production is READ-ONLY: Enforced at PostgreSQL connection level via default_transaction_read_only=on
  2. Credentials in personal config: Production credentials are stored in your personal ~/.cursor/mcp.json, not in the repository
  3. 1Password integration: Use op signin for secure credential retrieval
  4. Docker isolation: postgres-mcp runs in containers, not directly on host

Required PostgreSQL Extensions

For full postgres-mcp functionality, these extensions should be installed:

Extension Purpose Required For
pg_stat_statements Query statistics Slow query analysis
hypopg Hypothetical indexes Index tuning suggestions

Install on server (Ubuntu):

apt install postgresql-16-hypopg
sudo -u postgres psql -d heatwave -c "CREATE EXTENSION IF NOT EXISTS hypopg;"

No restart required for hypopg — it loads on-demand.

Example Queries

Performance Analysis

"Show slow queries from pg_stat_statements on production"
"Find tables with high sequential scan rates"
"Check index usage statistics"

Replication Monitoring

"Check replication status on production"
"Show replication lag between primary and replica"
"Is the replica streaming?"

Health Checks (postgres-mcp built-in)

"Run a health check on the production database"
"Analyze index health and find bloated indexes"
"Check for duplicate indexes"
"Analyze vacuum health"

Last Updated: November 26, 2025