Windsurf

Windsurf's Cascade agent. One JSON file — but not the same JSON as everyone else's, which is worth reading before you paste anything.

The one difference that matters. Windsurf wants serverUrl, where Cursor, Claude Desktop and most others want url. A config copied from another tool's instructions will look right and do nothing. If you take one thing from this page, take that.

Before you start#

You need: Windsurf installed.

You will know it worked when: The MCP panel lists gradworkbench with tools next to it — not zero.

Your workspace address is your app's address with /api/mcp on the end. The block on Settings → Research Access has yours already filled in, with a copy button — use that rather than typing it.

Where the file goes#

~/.codeium/windsurf/mcp_config.json

You can also reach it without a text editor: click the MCP icon at the top right of the Cascade panel, or go to Settings → Cascade → MCP Servers, and open the raw configuration from there.

Sign in — the short way#

1. Put this in mcp_config.json. If the file already has an mcpServers block, add the entry inside it rather than replacing the file:

{
  "mcpServers": {
    "gradworkbench": {
      "serverUrl": "https://gradworkbench.vercel.app/api/mcp"
    }
  }
}

2. Save it, and press Refresh in the MCP panel.

3. Windsurf prompts you to authorise the server. Approve it in the browser that opens.

Use a key instead#

1. In Settings → Research Access, issue a key with Read your workspace and Submit research ticked. Copy it — it is shown once.

2. Add a headers block:

{
  "mcpServers": {
    "gradworkbench": {
      "serverUrl": "https://gradworkbench.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_key_here" }
    }
  }
}

3. Save and refresh the MCP panel.

Connect the second one, so research gets checked#

Whatever submits a finding is refused when it tries to confirm that same finding. Add a second entry under a second name, with a second key that has Read your workspace and Check research ticked — and not Submit research:

{
  "mcpServers": {
    "gradworkbench": {
      "serverUrl": "https://gradworkbench.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_first_key" }
    },
    "gradworkbench-verify": {
      "serverUrl": "https://gradworkbench.vercel.app/api/mcp",
      "headers": { "Authorization": "Bearer sk_your_second_key" }
    }
  }
}

Try it#

In Cascade:

What's in my GradWorkbench workspace? Just summarise it — don't research anything.

If it comes back with your universities and professor counts, you are connected. Go to what to actually say.

When it doesn't work#

The server is listed but has no tools — almost always url where it should say serverUrl. Windsurf treats an entry it cannot make sense of as a local command server and finds nothing to run.

Nothing appeared at all — invalid JSON, or the file is in the wrong place. It is ~/.codeium/windsurf/mcp_config.json, under .codeium rather than .windsurf, which catches people out.

Changes don't take — press Refresh in the MCP panel. Windsurf does not watch the file.

Your Windsurf looks different from this — newer versions moved MCP configuration out of Cascade and into a CLI-managed config. If Settings → Cascade → MCP Servers isn't there, check your version's own documentation for the file it reads; the entry shape in this page is what goes in it.

← Back to Connecting your assistant