Windsurf · Cascade · ~/.codeium/windsurf/mcp_config.json

Image generation in Windsurf: MCP server setup

Add one entry to ~/.codeium/windsurf/mcp_config.json with a serverUrl field and your key as a header, refresh the MCP panel, and Cascade gains eleven image tools. Cascade already reads your codebase and edits across files. Add the server and it can also produce the artwork those files need — no tab switch, no download folder, no forgotten asset.

By the imagemcpserver.com teamPublished Updated
Get a free API key See all eight tools

The config entry

~/.codeium/windsurf/mcp_config.jsonpaste and refresh
{
  "mcpServers": {
    "imagemcp": {
      "serverUrl": "https://mcp.imagemcpserver.com/mcp",
      "headers": {
        "x-api-key": "sk-img-gen-your_key_here"
      }
    }
  }
}

Remote servers are shaped differently. They take serverUrl (or url) rather than command and args. A config copied from a stdio example — or from our Cursor or Claude pages — will not connect.

If your build wants a command instead: use "command": "npx" with "args": ["-y", "mcp-remote", "https://mcp.imagemcpserver.com/mcp", "--header", "x-api-key:sk-img-gen-…"]. Same tools, one local bridge process.

Which agent are you in?

Windsurf’s documentation now sits under Devin, and the desktop app is referred to as Devin Desktop there. The mcp_config.json file on this page is the Cascade configuration. Newer local-agent tabs read MCP configuration from the Devin CLI config files instead, so if a correct entry here is invisible to the agent you are talking to, check which agent that tab is running before editing anything else. Checked September 2026.

Keeping the key out of the file

mcp_config.json supports interpolation inside serverUrl, url and headers, so the key never has to sit in the file as plain text.

  • ${env:IMAGEMCP_API_KEY}

    Reads an environment variable. Note that an unset variable resolves to an empty string rather than erroring — which looks exactly like a bad key.

  • ${file:~/.secrets/imagemcp.txt}

    Reads the trimmed contents of a file, tilde paths included. This is the one to reach for when a GUI launch does not inherit your shell environment.

key from the environment
{
  "mcpServers": {
    "imagemcp": {
      "serverUrl": "https://mcp.imagemcpserver.com/mcp",
      "headers": {
        "x-api-key": "${env:IMAGEMCP_API_KEY}"
      }
    }
  }
}

Eleven tools, and a ceiling of 100

Each arrives with its full JSON schema, so Cascade knows the parameters, the enums and which fields are required without you explaining any of it.

generate_image

text-to-image and image-to-image

generate_transparent_image

generate + cut out in one call

edit_image

inpaint, retouch, restyle

remove_background

alpha cutout

upscale_image

2x / 4x / 8x

text_to_svg

real vector paths

compress_image

quality-controlled re-encode

convert_format

six raster formats

multicall

run the above in parallel

get_user_info

credits and plan · free

list_models

live model catalogue · free

Cascade caps out at 100 tools in total

That ceiling is across every MCP server you have connected, not per server. This one takes eleven of it. If you run several large servers you can genuinely hit the limit, and the fix is to toggle individual tools off on each server’s settings page rather than removing a whole server — turning off convert_format and list_models costs you very little here. Checked September 2026.

Confirm it is live

Refresh the MCP panel — servers are read at load, so an edit alone will not register — then ask Cascade something only the server can answer:

“Check my image credit balance and list the models I can use.”

Both calls are free. If Cascade returns real numbers and a real model list, the connection is good and you have spent nothing to find out.

Four fixes that cover most failures

Nothing appears in the panel

The JSON is malformed, or the file was created in the wrong directory. Validate it, then confirm the path.

The entry uses command instead of serverUrl

A remote server configured in the stdio shape will never connect. This is the most common copy-paste failure.

Server shows but tools error

The key is wrong, revoked, or an interpolated variable resolved to nothing. Test the key with a direct curl before blaming the client.

Tools appear but never get called

Cascade will not reach for a tool it has no reason to use. Say “generate an image with the imagemcp tools” explicitly the first time.

Team allowlists

On a team plan an administrator can turn MCP off entirely or allowlist approved servers, and the allowlist has one behaviour worth knowing before it catches you out.

One entry blocks everything else

By default everyone can add their own servers. The moment an admin allowlists a single server, every server not on the list is blocked for the whole team. Adding one entry is not an additive change — it switches the policy from open to closed.

The server ID is case-sensitive

The ID in the allowlist has to match the key name in each user’s mcp_config.json exactly. If the allowlist says imagemcp, a user with imageMCP is blocked.

Windsurf questions

How do I add an MCP server to Windsurf?

Open the MCP panel — the MCPs icon in the top right of the Cascade panel, or Settings → Cascade → MCP Servers — and install from the marketplace, or click through to edit mcp_config.json for anything not listed there. Remote servers like this one go in by hand. Refresh the panel afterwards; servers are read at load.

Where is the Windsurf MCP config file?

At ~/.codeium/windsurf/mcp_config.json. You can also reach it from the MCP panel in settings, which opens the same file — editing either way is equivalent.

Why does my remote server entry not work?

Remote HTTP servers use a different shape from local ones: they need a serverUrl (or url) field rather than command and args. An entry copied from a stdio example, or from a Claude or Cursor config, will not connect.

Is there a limit on how many MCP tools Cascade can use?

Yes — Cascade has a ceiling of 100 tools in total across every MCP server you have connected. This server contributes eleven. If you are running several large servers you can hit it, and the fix is to toggle individual tools off on each MCP's settings page rather than removing whole servers. Checked September 2026.

Can I keep the API key out of the config file?

Yes. mcp_config.json supports interpolation in serverUrl, url and headers, so you can use ${env:IMAGEMCP_API_KEY} to read it from the environment, or ${file:~/.secrets/imagemcp.txt} to read it from a file. The file form is handy when a GUI launch does not inherit your shell environment.

My Windsurf build only accepts command-based servers. What then?

Use the npx mcp-remote form. It spawns a local bridge that speaks stdio to Windsurf and HTTP to the endpoint, which works regardless of what remote transports your build supports.

Can Cascade run several image operations at once?

Yes, through the multicall tool. It takes a list of tool calls and executes them concurrently, which matters when a single request needs a dozen assets.

What does it cost to try?

Nothing. The free tier is 30 credits a month with no card, and the two account tools — get_user_info and list_models — never deduct credits at all.

Sources & references

Using a different editor?

CursorGitHub CopilotClineClaude Code