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.

  1. Add Toolspoke to Claude Code

    Run it in your project, then /mcp to sign in

    claude mcp add --transport http toolspoke https://toolspoke.com/mcp

    The sign-in opens in your browser, and Toolspoke asks you to approve it.

  2. 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.
  3. 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.

Try PostgreSQL in Claude Code

Free to start, and tool calls cost nothing on any plan.