Windsurf MCP server for diagrams: serverUrl, headers, and the file Cascade reads

Cascade reads MCP servers from mcp_config.json under the Codeium configuration directory in your home folder, at ~/.codeium/windsurf/mcp_config.json on macOS and Linux and the equivalent path under your user profile on Windows. The file is not created for you, so the first setup is a new file rather than an edit. From inside the editor, the MCPs control in the Cascade panel has a Configure action that opens it.

For a remote server the entry needs serverUrl and, for an authenticated one, headers. The field is serverUrl rather than url, which is the single most common reason a Windsurf entry copied from another client does nothing. Datadef has no dedicated Windsurf recipe on the settings page, so use the generic Streamable HTTP form: the endpoint accepts any client that can send a bearer token.

Both serverUrl and headers support variable interpolation, so the key can come from the environment instead of sitting in the file. That matters more than usual here because the config lives in your home directory and tends to accumulate every server you have ever tried.

The second block below is the bridge form, and it is the one to reach for if the direct entry registers nothing. It launches mcp-remote as a stdio command that forwards the Authorization header to the same endpoint, which is exactly what the Claude Desktop, Cursor and VS Code recipes do, so it does not depend on how a given Windsurf build declares a remote server.

// ~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "datadef": {
      "serverUrl": "https://datadef.io/mcp",
      "headers": {
        "Authorization": "Bearer ${env:DATADEF_API_KEY}"
      }
    }
  }
}

// Fallback for a build that only launches stdio servers:
// the same bridge every desktop client uses.
{
  "mcpServers": {
    "datadef": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://datadef.io/mcp",
        "--header", "Authorization: Bearer ${env:DATADEF_API_KEY}"
      ]
    }
  }
}

Cascade already has the repository, so the useful prompts are the ones that ask it to draw what it just read. The server gives it create_diagram for a first pass, edit_diagram for a described change, and 27 canvas tools for element-level control: adding nodes, connecting and labelling edges, grouping into zones, setting table columns, drawing column-level lineage, and laying the result out.

Two of those tools are worth naming in the prompt. canvas_validate_canvas reports orphan nodes and overlapping elements, and canvas_measure_canvas reports the actual dimensions. A session that ends with a validation pass produces something reviewable; one that ends at the last add call usually needs a human to tidy it.

For a project already connected to a repository, repo_status reports which provider and branch or tag it tracks, the commit it reflects, whether daily sync is on, and how long ago the last one ran. repo_refresh runs a sync now. Both answer only to the account that owns the repository connection, so a teammate's credential cannot trigger a sync on your connection.

Work through it in the order that costs least. The field name first, since serverUrl and url are not interchangeable here. The file path second, because a config written next to the project rather than under the Codeium directory is never read. A restart third, since the list is built at startup. Then swap the direct entry for the mcp-remote bridge block, which removes the question of how this build declares a remote server. Then the credential.

Before rewriting the config a fourth time, prove the server itself. Listings on this endpoint are anonymous: a single POST asking for tools/list returns all 36 tools with no credentials attached. If that answers and Cascade still shows nothing, the problem is entirely local, and no amount of key regeneration will change it.

curl -s https://datadef.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

• MCP server documentation and client setup
• Cursor MCP config for a diagram server
• VS Code MCP server for diagrams
• Draw diagrams with your AI agent over MCP