Postgres

Key Concepts

• toolbox: The MCP utility that brokers all PostgreSQL connections — never use direct psql or shell commands.
• Connectivity probe: A lightweight read-only call (e.g., list tables) made before every user request to confirm the server is reachable.
• Read-only default: Prefer SELECT queries; only execute INSERT/UPDATE/DELETE when the user explicitly requests a data change.
• Schema-first: Always inspect table structure before querying unfamiliar tables to avoid incorrect column references.

Workflow

1. Connectivity probe — call a lightweight read-only tool (e.g., list databases or list tables) as the first action. If it fails, stop immediately and report: "PostgreSQL MCP server is unavailable. Cannot proceed." Do not fall back to shell/bash.
2. Understand the schema — for unfamiliar tables, inspect columns and types before constructing queries.
3. Execute query — run the appropriate MCP tool with a safe, targeted SQL statement.
4. Report using this structure:
   • Answer: direct response to the user's question
   • Data: query results, counts, or summaries
   • Source: table/view name(s) used

Usage Examples

List Databases

postgres Show all available databases

Schema Inspection

postgres List all tables and their columns in the public schema

Data Query

postgres Show the 10 most recent user registrations from the users table

Aggregation / Analysis

postgres Analyze order counts grouped by status over the last 30 days

Row Count Overview

postgres How many rows are in each table?

Configuration

MCP server is called toolbox (local process) and is configured in postgres.agent.md. Environment variables (host, port, credentials) are defined in .claude/.env.

Do NOT search the filesystem for config files directly — always route through the postgres agent file.

Best Practices

• Always run a connectivity probe before executing any user-requested query
• Always inspect schema first when querying unfamiliar tables
• Prefer read-only queries; confirm with the user before executing any write operation
• Use MCP toolbox exclusively — never use psql, bash, or direct shell commands
• Include LIMIT clauses on open-ended queries to avoid large result sets

Limitations

• Sandbox PostgreSQL instance only — not for production databases
• Requires the toolbox utility to be installed and running
• MCP server must be configured and reachable
• Write operations (INSERT/UPDATE/DELETE) should be used with caution
• Very complex queries or stored procedure calls may not be supported

Security Considerations

• Credentials are managed exclusively by the MCP server configuration — never hardcode or log them
• Avoid returning or displaying sensitive columns (e.g., passwords, tokens) in query results
• Use the principle of least privilege: prefer read-only access patterns