Connect PostgreSQL to Claude Code
Inspect the schema of a PostgreSQL database. Add Toolspoke to Claude Code once and it can use 12 PostgreSQL actions. Your PostgreSQL credential stays in Toolspoke, and you choose which actions Claude Code may call.
Set it up in Claude Code
Three steps, the first one once for every toolkit you will ever add.
Add Toolspoke to Claude Code
Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcpThe sign-in opens in your browser, and Toolspoke asks you to approve it.
Install PostgreSQL and connect it
Add PostgreSQL to a project in your Toolspoke workspace.
Connection URL. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.
- Connection URL
- Use a read-only role where possible. Append ?sslmode=require for managed providers.
Choose what Claude Code may do
All 12 actions only read, and any of them can be switched off for a project.
What you can ask Claude Code for
A few of the PostgreSQL actions that only read, so they are safe to try first.
- Report the PostgreSQL version, current database and role, database size and timezone
- List the non-system schemas in the database with their owner and table count
- List tables (and optionally views) with their kind, planner row estimate, total size on disk and comment
- List indexes with their definition, uniqueness, size and how many times the planner has used them
What Claude Code can do in PostgreSQL
12 actions read.
Reads
Server info
Report the PostgreSQL version, current database and role, database size and timezone. Call this first to confirm the connection works.
List schemas
List the non-system schemas in the database with their owner and table count. Use it to find where the application's tables live before calling list_tables.
List tables
List tables (and optionally views) with their kind, planner row estimate, total size on disk and comment. The row counts are estimates from the planner statistics, not exact counts.
List tables and views
List tables, views and materialised views with their kind, planner row estimate, total size on disk and comment. Use list_tables when you only want real tables.
Describe table
Describe one table or view: every column with its position, type, nullability, default, primary-key membership and comment. Use this before writing a query against an unfamiliar table.
List indexes
List indexes with their definition, uniqueness, size and how many times the planner has used them. Unused indexes on large tables are the usual thing to look for.
List foreign keys
List foreign-key constraints and what they reference, so you can work out how tables join before writing a query.
Table sizes
List the largest tables by total size on disk, split into heap and index bytes with a planner row estimate. Use it to find what is filling the database.
List extensions
List installed extensions with their version and schema, for example pgvector, postgis or pg_stat_statements.
Run query
Run one read-only SQL query and return the rows. Only a single SELECT, WITH, TABLE or VALUES statement is accepted, no semicolon-separated statements, no INSERT/UPDATE/DELETE/DDL, and the connection is opened in a read-only transaction with a 15 second statement timeout. Results are always capped by `limit`.
Explain query
Return the PostgreSQL execution plan for a read-only query as JSON. Set `analyze` to actually run the query and get real timings and row counts; leave it off for a plan-only estimate. Same read-only restrictions as run_query.
List activity
List the current sessions on this database, oldest query first, with state, wait event and a truncated query text. Use it to find long-running or blocked queries. Read-only, it cannot cancel anything.
PostgreSQL in Claude Code: questions
Does Claude Code see my PostgreSQL credential?
No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.
Will 12 actions crowd Claude Code's context?
No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the PostgreSQL action it needs when it needs it. Adding more toolkits does not add more tools to its list.
Can I add it once for every project?
Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.
What does it cost?
Tool calls are free on every plan. PostgreSQL runs in a sandbox, so a call bills the sandbox time it uses.
PostgreSQL in your other apps
Try PostgreSQL in Claude Code
Free to start, and tool calls cost nothing on any plan.