MCP Toolbox for Databases for Windsurf: Setup & Config

What you can do with MCP Toolbox for Databases in Windsurf

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

• Explore database schemas from a coding assistant.
• Run database queries through prebuilt MCP tools.
• Observe database-tool activity with metrics and tracing.

Before you start: MCP Toolbox for Databases in Windsurf

• 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 Windsurf configuration

1. Choose Windsurf configuration scope

   For MCP Toolbox for Databases, open macOS/Linux: ~/.codeium/windsurf/mcp_config.json Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json. Merge into mcpServers; remote endpoints use serverUrl.

2. Add MCP Toolbox for Databases to Windsurf

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

3. Check MCP Toolbox for Databases in Windsurf

   MCP Toolbox for Databases: Refresh MCP in Windsurf settings and inspect Cascade’s tools.

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

MCP Toolbox for Databases tools available to Windsurf

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

list_tables

After refreshing MCP Toolbox for Databases in Windsurf settings, check Cascade's tool list for list_tables.

execute_sql

After refreshing MCP Toolbox for Databases in Windsurf settings, check Cascade's tool list for execute_sql.

Execute SQL through the database's prebuilt tool interface.

MCP Toolbox for Databases: full stored tool descriptions

Troubleshooting MCP Toolbox for Databases in Windsurf

• Check npx @toolbox-sdk/server (Node.js/npm) on the machine running Windsurf's MCP integration for MCP Toolbox for Databases; refresh MCP and inspect Cascade's tools.
• MCP Toolbox for Databases uses stdio here: Windsurf 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 Windsurf troubleshooting lives in the /clients/windsurf guide.

Frequently asked questions