MCP Toolbox for Databases for Claude Code: Setup & Config

What you can do with MCP Toolbox for Databases in Claude Code

Use one database-tool framework for exploratory assistants and deliberately scoped production queries.

• Define parameterized custom operations for production agents.
• Group database tools into task-specific toolsets.
• Observe database-tool activity with metrics and tracing.

Before you start: MCP Toolbox for Databases in Claude Code

• An MCP-compatible client
• npx for this execution method
• A PostgreSQL database for this example
• Database-specific connection settings from the prebuilt reference

This is the README's prebuilt PostgreSQL example. Exact database connection environment variables are not stated in the supplied README, so none are invented here. Binaries and containers are recommended for a more standard installation. The repository is now named mcp-toolbox.

MCP Toolbox for Databases Claude Code configuration

1. Choose Claude Code configuration scope

   For MCP Toolbox for Databases, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add MCP Toolbox for Databases to Claude Code

   Use the genai-toolbox entry below in mcpServers. Keep MCP Toolbox for Databases's documented stdio connection fields and your other Claude Code entries.

3. Check MCP Toolbox for Databases in Claude Code

   MCP Toolbox for Databases: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "genai-toolbox": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@toolbox-sdk/server",
        "--prebuilt=postgres",
        "--stdio"
      ],
      "env": {}
    }
  }
}

claude mcp add-json --scope project 'genai-toolbox' '{"type":"stdio","command":"npx","args":["-y","@toolbox-sdk/server","--prebuilt=postgres","--stdio"],"env":{}}'

MCP Toolbox for Databases tools available to Claude Code

MCP Toolbox for Databases's stored tool list documents 2 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

list_tables

For MCP Toolbox for Databases's list_tables, review the permission request and arguments in Claude Code before approval.

Discover database tables through a prebuilt generic tool.

execute_sql

For MCP Toolbox for Databases's execute_sql, review the permission request and arguments in Claude Code before approval.

MCP Toolbox for Databases: full stored tool descriptions

Troubleshooting MCP Toolbox for Databases in Claude Code

• If MCP Toolbox for Databases fails to start, check npx @toolbox-sdk/server (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• MCP Toolbox for Databases uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: Connection configuration is database-specific and requires separate reference details.
• Known limitation: The README characterizes npm execution as convenience-oriented rather than the most reliable installation.
• Known limitation: Custom tools require source and query definitions.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions