windsurf-database-mcp

Wiring a free cloud database into Windsurf's Cascade agent as an MCP server, with a Redis dataset to try it against.

Three things that trip people up

Almost every failed Windsurf MCP setup is one of these, and none of them produce a useful error.

The key is serverUrl, not url. Cursor, Zed and Warp all use url. Windsurf does not. An entry with url is parsed, accepted, and then does nothing — no red state, no log line, the server just has no tools. If you copied a snippet from any other editor's docs, this is your bug.

The documentation moved. Following Cognition's acquisition of Windsurf, the product's docs now live at docs.devin.ai, under the Devin family. Older docs.windsurf.com and docs.codeium.com links still float around search results and some of them describe an earlier config shape. Check the current page before trusting a snippet.

Enterprise tenants have MCP switched off by default. If you are on an Enterprise plan, an admin has to enable MCP for the organisation before any server you configure will load. Individual and team plans do not need this. Symptom: your JSON is perfect, the plugin panel is empty, and nothing you change locally helps.

The setup

Edit ~/.codeium/windsurf/mcp_config.json — the directory name is still .codeium, a leftover from before the rename. Create the file if it is not there.

{
  "mcpServers": {
    "harbour": {
      "serverUrl": "https://freebase.cloud/api/mcp/YOUR_TOKEN"
    }
  }
}

That is the entire remote-server form: a name and a URL. No transport field, no command, no args, no env, no headers. The token sits in the URL path, so there is nothing to authenticate separately — which is convenient, and also means the file is a credential. Keep it out of dotfile repos.

You can also reach the same file through the UI: Windsurf Settings → Cascade → Plugins → View raw config. The panel is the friendlier route for adding, and the file is the faster route for editing. After saving, press Refresh in the plugin panel. Cascade re-reads the config without a restart.

harbour is the name that prefixes every tool. Choose it for the data, not the engine — you will be reading these names in Cascade's tool-call output for as long as the server is registered.

Getting the endpoint

Sign up at freebase.cloud — free, no card. Create a session, pick your engine, then Settings → MCP → New Token, select the connection, copy the URL. It has the form https://freebase.cloud/api/mcp/YOUR_TOKEN and it speaks streamable HTTP, which is what Windsurf's remote-server support expects.

What Cascade can do once it is loaded

Four tools, prefixed with the connection name:

• harbour_list_tables — what exists: tables, collections, keyspaces, indices, measurements
• harbour_query — read, in the engine's own language
• harbour_store — write
• harbour_annotate_table — record what a table means, so later queries are informed rather than inferred

The same four tools appear on every engine, which is why the matrix further down differs only by dialect.

Cascade shows each call in the conversation before it runs, and you approve or reject it. If you want the read tools to run unattended but not the writes, that distinction is per-tool in the plugin panel — leave harbour_store requiring approval.

Verifying it, from both sides

From the editor, the cheapest possible check is to ask Cascade:

List everything in the database and tell me which key patterns are in use.

If it answers without calling a tool, it is answering from imagination — look at the tool-call trace rather than the prose. If it calls harbour_list_tables, you are done.

From the shell, examples/cascade_preflight.py does the handshake independently. It is the faster way to tell a broken token apart from a broken config, because it never touches Windsurf. A revoked one is replaced from the MCP settings.

Redis, worked

The dataset in examples/harbour_board.sh is a small ferry-terminal departure board, written for a free Redis 7.2.3 instance. It uses the data structures Redis is actually good at rather than treating it as a key/value bucket:

• a sorted set per route, scored by departure timestamp, so "next three sailings" is one ZRANGE
• hashes for the sailing records themselves
• a plain counter with a TTL for foot-passenger tallies that should reset overnight
• pub/sub for delay announcements

Redis is one of three engines here that accept a native driver over the real wire protocol (redis://HOST:6379, RESP2), alongside PostgreSQL and MongoDB. So redis-cli, ioredis, redis-py and Lettuce connect unmodified, and Cascade sees the same keyspace through MCP. The other twelve engines are reached over HTTP and MCP only.

Engine matrix

Engine	Version	Dialect Cascade writes
PostgreSQL	16.2	SQL
MySQL / MariaDB	8.0.36 / 11.3.2	SQL
SQLite	3.45.1	SQL
CockroachDB	23.2.4	SQL
TimescaleDB	2.14.2	SQL
MongoDB	7.0.4	aggregation pipeline
Redis	7.2.3	Redis commands
Cassandra	4.1.4	CQL
DynamoDB	2024.1	item operations
ClickHouse	24.1.5	OLAP SQL
Elasticsearch	8.12.0	query DSL
Neo4j	5.17.0	Cypher
InfluxDB	2.7.4	Flux / InfluxQL
Prometheus	2.50.1	PromQL

One token maps to one connection. Add more entries to mcpServers for more databases, each with its own name.

When Cascade says the server is unavailable

Start with the config file itself, because a JSON syntax error is invisible in the plugin panel — python3 -m json.tool ~/.codeium/windsurf/mcp_config.json will tell you in a second what the UI never will. Then confirm the key really is serverUrl; it is worth re-reading the line rather than assuming, since url looks correct to the eye.

If the JSON is clean, separate the two halves of the problem. Run the preflight script. A working handshake there and a dead server in Windsurf means the editor is at fault: hit Refresh in the plugin panel, and if that does nothing, restart Windsurf so the plugin host reloads. A failing handshake means the token has been revoked or mistyped, and you should generate a fresh one.

That leaves two less common cases. On Enterprise plans, MCP has to be enabled organisation-wide first — nothing in the local config can work around it. And if you have many servers registered, Cascade limits how many tools it will present in one conversation, so an over-full plugin list can push the database tools out of scope. Disable what you are not using.

Honest limits

The free tier is intended for development, prototyping and small production workloads. There is no published SLA, no uptime commitment and no managed backup product, so treat anything valuable as something you export yourself. MCP is an agent channel: your application should still talk to the database through a normal driver.

Repo contents

examples/
  mcp_config.json        drop straight into ~/.codeium/windsurf/
  cascade_preflight.py    handshake + tool list, no dependencies
  harbour_board.sh        redis-cli script: the ferry departure board dataset
  README.md

Links

• Free Redis cloud instance
• Connecting Claude to Redis
• Engine list and signup
• MCP specification — current revision 2026-07-28
• Redis commands reference

---

freebase.cloud is an independent service and is not affiliated with Cognition, Windsurf, Redis Ltd., or any of the database projects named in the matrix above — the PostgreSQL Global Development Group, Oracle (MySQL), MariaDB Foundation, SQLite, Cockroach Labs, Timescale, Inc., MongoDB, Inc., the Apache Software Foundation (Cassandra), Amazon Web Services (DynamoDB), ClickHouse, Inc., Elasticsearch B.V., Neo4j, Inc., InfluxData or Prometheus.