MCP Toolbox for Databases in Windsurf.
Give Cascade a real connection to your database. One entry in mcp_config.json and Windsurf's agent can inspect schemas and run queries through Google's MCP Toolbox.
MCP Toolbox for Databases (github.com/googleapis/genai-toolbox, 15.5k stars) is Google's open-source MCP server for database access. Instead of pasting schema dumps into chat, you point the Toolbox at your database and Windsurf's Cascade agent gets tools to query it directly — with connection pooling and auth handled by the Toolbox, not by your prompt.
Windsurf reads MCP servers from a single global file, so setup is one JSON entry plus a refresh. This guide uses the Toolbox's container image, since the project ships as an OCI package rather than an npm module.
Before you start
You need Docker running locally (the Toolbox distributes as a container image; a standalone binary also exists if you prefer to download it from the GitHub releases page), a database the Toolbox can reach, and Windsurf with Cascade enabled.
The Toolbox supports prebuilt configurations for common engines — the example below uses the postgres prebuilt, which exposes query and schema tools without you writing a tools file. For custom tool definitions you would mount a tools.yaml instead; check the genai-toolbox docs for that format.
Add the server to mcp_config.json
Open Windsurf Settings > Cascade > MCP Servers > Add Server, or edit the global config file directly at ~/.codeium/windsurf/mcp_config.json. Either route writes the same JSON. Add an entry under mcpServers that launches the Toolbox container in stdio mode:
{
"mcpServers": {
"database-toolbox": {
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "POSTGRES_HOST=host.docker.internal",
"-e", "POSTGRES_PORT=5432",
"-e", "POSTGRES_DATABASE=app",
"-e", "POSTGRES_USER=readonly",
"-e", "POSTGRES_PASSWORD=YOUR_PASSWORD",
"us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest",
"--prebuilt", "postgres", "--stdio"
]
}
}
}Refresh Cascade and verify
Windsurf does not pick up config edits live. Go back to Settings > Cascade > MCP Servers and hit the refresh control (or restart Windsurf entirely) so it re-reads mcp_config.json. The database-toolbox entry should appear in the server list with its tools enumerated.
Test it by asking Cascade something that requires the database — "what tables exist in the app schema?" is a good first prompt because it exercises schema introspection without touching data. Use a read-only database role for the credentials above until you trust the workflow.
Troubleshooting in Windsurf
Server missing after refresh: almost always a JSON syntax error in mcp_config.json — a trailing comma or unescaped backslash will make Windsurf silently skip the file. Validate the JSON before blaming anything else.
Spawn failures: Windsurf launches the command as a child process, so docker must be on the PATH the GUI app sees. On macOS, apps launched from the Dock get a narrower PATH than your terminal; if docker lives somewhere unusual, use its absolute path in the command field.
Connection errors inside the container: localhost inside Docker is the container, not your machine. That is why the example uses host.docker.internal for a locally running Postgres. For a remote database, put its real host in POSTGRES_HOST and make sure the container's network can reach it.
The Toolbox on Loomal
MCP Toolbox for Databases has a live listing on the Loomal marketplace at https://loomal.ai/marketplace/mcp-toolbox-for-databases, with its package details and tool list alongside the rest of the Databases category. If you maintain a database-facing MCP server yourself, the same index is where you can claim your listing and attach x402 per-call pricing to a hosted endpoint.
FAQ
How do I install MCP Toolbox for Databases in Windsurf?
Add a mcpServers entry to ~/.codeium/windsurf/mcp_config.json (or use Settings > Cascade > MCP Servers > Add Server) that runs the Toolbox container with docker run -i and the --stdio flag, then refresh the MCP Servers panel. Cascade will list the Toolbox's database tools once the server starts.
Where does Windsurf keep its MCP configuration?
In a single global JSON file at ~/.codeium/windsurf/mcp_config.json. Windsurf has no per-project MCP config, so the Toolbox will be available in every workspace once added. Edits require a refresh from the Cascade settings panel or a full restart.
Do I have to use Docker?
No. The genai-toolbox project also publishes standalone binaries on its GitHub releases page. If you install one, set command to the binary's path and pass the same --prebuilt postgres --stdio arguments. Docker is just the most portable route since the official package is an OCI image.
The server starts but queries fail — why?
Usually the database connection, not MCP. Check that the host is reachable from inside the container (use host.docker.internal for a local database), the credentials are right, and the role has permission on the schema. The Toolbox prints connection errors to stderr, which Windsurf surfaces in the server's status.
Browse more MCP servers for Windsurf.
Every listing on the Loomal index shows package, tools, and pricing.