# Connect SocialCutter to Windsurf (Cascade) over MCP
> Add the SocialCutter MCP server to Windsurf: both mcp_config.json paths, serverUrl, the X-API-Key header and the errors you will actually hit.
- URL: https://socialcutter.theboomer.dev/en/guides/windsurf/
- Idioma: en
- Familia: ia
- Actualizado: 2026-09-24
- Palabras clave: Windsurf, Cascade, MCP, mcp_config.json, serverUrl, X-API-Key, SocialCutter
## Why connect SocialCutter to Windsurf

Windsurf is Codeium's editor with a built-in agent, and Cascade is the agent that runs inside it. Once you attach an MCP server, Cascade no longer needs you to paste HTTP requests: you describe what you want in plain language and it picks the tool and fills in the parameters.

The SocialCutter MCP server exposes the API as **28 tools**: process an image, read history, wallet, coupons, API keys and billing. The protocol, the tools and the connection modes are all covered in the [SocialCutter MCP server guide](/en/guides/mcp/); this page focuses on what is specific to Windsurf: where the file goes, what each field is called, and what Cascade does differently.

One authentication detail is worth fixing up front. SocialCutter accepts both headers: **`X-API-Key: sc_...`** and **`Authorization: Bearer sc_...`**. Use whichever your client documents; the result is identical. A `Bearer` without the `sc_` prefix is treated as a session token and will return 401. Windsurf supports custom headers, so either works — copy the vendor's generic `Bearer` example and drop in your `sc_...` key and it connects just the same.

## The two mcp_config.json paths

Here is a detail that trips people up, so it is worth stating plainly: the **vendor documentation publishes two different paths** for the same file.

- The Cascade page shows `~/.codeium/windsurf/mcp_config.json`.
- The plugins page shows `~/.codeium/mcp_config.json`, which looks like the more recent one.

Both are plausible and the file name is identical (`mcp_config.json`); only the directory changes. A recent installation most likely reads the second one, while a setup that has been around for a while may still read the first.

| Path | Where it appears | When it tends to be the right one |
|---|---|---|
| `~/.codeium/windsurf/mcp_config.json` | Cascade page | Setups that already had a file in place |
| `~/.codeium/mcp_config.json` | Plugins page | Recent versions |

**How to find out which one your version reads.** No command reports it, so check by hand in three steps:

1. Open the `~/.codeium/` directory and look for `mcp_config.json` at the root or inside `windsurf/`. If one already exists, that is the one your installation reads: edit it and do not create another.
2. If neither exists, create the file at the path your version documents (when in doubt, start with `~/.codeium/mcp_config.json`) and start Windsurf.
3. Check the editor's MCP panel to see whether `socialcutter` shows up and whether its tools load. If it does not appear, try the identical block at the other path: the content is the same, so copying the whole file across costs nothing.

On Windows the `~` is your user folder, so `~/.codeium/mcp_config.json` is `C:\Users\your_user\.codeium\mcp_config.json`.

## The server JSON block

For remote MCP the documentation requires the `serverUrl` field (or `url`, if your version accepts the alias). A local server would use `command`; that is not our case, because the endpoint is remote and speaks HTTP.

```json
{
  "mcpServers": {
    "socialcutter": {
      "serverUrl": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "sc_your_key" }
      // Authenticates the same: "headers": { "Authorization": "Bearer sc_your_key" }
    }
  }
}
```

Three things in this block are worth leaving alone:

- **`serverUrl`** with the exact endpoint, including the trailing `/mcp`.
- **`headers`** with `X-API-Key`. No tool accepts the key as an argument: authentication always travels in a header, which is why the client has to support custom headers. Windsurf does.
- **`mcpServers`** as the root key, with whatever server name you prefer in lowercase; `socialcutter` is the name used across the documentation so the examples line up.

You can also add it from the UI: **Settings → Tools → Windsurf Settings → Add Server**, or by opening the file with **View Raw Config**. The UI writes exactly the same structure, so nothing is lost if you prefer the visual editor.

## Variable interpolation in the header

Keeping the key in plain text inside a configuration file is not ideal, especially if the file ends up in a repository. Windsurf supports interpolation with two syntaxes:

| Syntax | What it resolves |
|---|---|
| `${env:VARIABLE}` | The value of an environment variable in the editor's process |
| `${file:path}` | The contents of a text file, such as a mounted secret |

The environment variable version keeps the secret out of the file:

```json
{
  "mcpServers": {
    "socialcutter": {
      "serverUrl": "https://mcp.socialcutter.theboomer.dev/mcp",
      "headers": { "X-API-Key": "${env:SOCIALCUTTER_API_KEY}" }
    }
  }
}
```

Export `SOCIALCUTTER_API_KEY` in the environment you launch Windsurf from and keep the key in your secrets manager, not in the file. Watch the difference between "what your shell sees" and "what the editor inherits": launched from a terminal, Windsurf inherits that terminal's variables; opened from the system menu, it may not.

## The 100 active tools limit

Cascade has a cap: **100 active tools at a time**. In practice that means every configured MCP server adds tools against the same counter. Our server publishes 28, so on its own it is nowhere near the limit, but with three or four other tool-heavy servers it is easy to go over and find that some tools stop appearing.

If tools go missing, the first check is to count how many are active across all servers and disable the ones you do not use. That is faster than reinstalling anything.

## Enterprise and the refresh button

Two operational details that generate support tickets every week:

- **On Enterprise plans**, MCP is a capability that has to be **enabled in settings**, and administrators can block it with server allowlists. If you are a user in an organisation and the server is nowhere to be found, check with your administrator whether MCP is enabled before touching the file.
- **You have to press refresh.** Adding the block and saving the file does not reload the tool list. Press the refresh button on the MCP panel — or restart the editor — so Cascade sees the new server and its 28 tools.

## Common errors

| Symptom | Likely cause | Fix |
|---|---|---|
| `401: Invalid or expired authentication token` | No header reaches the server, or a `Bearer` without the `sc_` prefix (treated as a session token) | Send your `sc_...` key in `X-API-Key`, or in `Authorization: Bearer sc_...` |
| `401: Invalid API key` | The key exists but is not valid: mistyped, revoked or from another account | Create a new one under Profile → API keys and replace the value |
| The server does not appear in the list | You edited the path your version does not read | Try the identical block at the other `mcp_config.json` path |
| The server appears but has no tools | You saved without refreshing | Press the refresh button or restart Windsurf |
| Tools are missing although the server is fine | You passed the 100 active tools limit | Remove servers or disable tools you do not use |
| Nothing appears inside your organisation | MCP is disabled or blocked by allowlist | Ask your administrator to enable MCP in Enterprise settings |
| The key does not resolve from `${env:...}` | The variable is not in the editor's environment | Launch Windsurf from the terminal where you exported it, or go back to the plain key |

## Next steps

- Protocol overview: [Use SocialCutter from your LLM or editor with MCP](/en/guides/mcp/)
- Code path: [Process images with the API from the terminal (curl)](/en/guides/curl/) and [from Python](/en/guides/python/)
- Strategy: [Automating social media images: the 4 paths](/en/guides/automatizar-imagenes-redes-sociales/)
- API reference: https://docs.socialcutter.theboomer.dev
- Dashboard: https://dash.socialcutter.theboomer.dev