Connect SocialCutter to Windsurf (Cascade) over MCP

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; 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.

{
  "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:

{
  "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
• Code path: Process images with the API from the terminal (curl) and from Python
• Strategy: Automating social media images: the 4 paths
• API reference: https://docs.socialcutter.theboomer.dev
• Dashboard: https://dash.socialcutter.theboomer.dev