Image generation MCP for Claude Code, Cursor and Codex

Why give a coding agent an image tool

Agents that build front ends keep hitting the same wall: the page needs a hero image, an empty-state illustration or a product shot, and the agent can only leave a placeholder. With an image generation MCP server connected, it can make the asset, save it into the repo and wire it into the component in the same turn.

The same tools work when the agent is building a feature rather than decorating one. Asked to add a "generate cover image" button, it can call the model while it writes the code, so it knows the real request and response shapes instead of guessing them.

The server

Windpaint runs a hosted MCP server over streamable HTTP at https://mcp.windpaint.ai/mcp. It's a thin client of the public API: each tool call is an ordinary API request made with your key, billed and scoped like one. The server stores nothing.

Authentication is a bearer header with an API key (aak_...) from Settings → API Keys in the dashboard. An optional X-Windpaint-Project header pins every call on the connection to one project. There is no OAuth flow yet, so clients that only connect through OAuth can't use it.

Claude Code

The plugin installs the MCP server plus five skills that teach Claude when to estimate, how to wait on a job and how to save outputs. From inside claude:

/plugin marketplace add windpaint-ai/skills/plugin install windpaint@windpaint

Run /mcp and windpaint should show as connected with 20 tools. If you only want the tools, add the server directly:

claude mcp add --transport http windpaint https://mcp.windpaint.ai/mcp \  --header "Authorization: Bearer $WINDPAINT_API_KEY"

To share the setup with a team, commit a .mcp.json at the project root that references ${WINDPAINT_API_KEY} and let each person export their own key. The Claude Code guide has the file.

Codex

Codex reads the key through bearer_token_env_var, so the config only names the variable:

codex plugin marketplace add windpaint-ai/skillscodex plugin add windpaint@windpaint

Or, for the tools without the skills, add this to ~/.codex/config.toml:

[mcp_servers.windpaint]url = "https://mcp.windpaint.ai/mcp"bearer_token_env_var = "WINDPAINT_API_KEY"

codex mcp get windpaint confirms the URL and variable. More in the Codex guide.

Cursor

Put this in .cursor/mcp.json for one project, or ~/.cursor/mcp.json for all of them:

{  "mcpServers": {    "windpaint": {      "url": "https://mcp.windpaint.ai/mcp",      "headers": {        "Authorization": "Bearer ${env:WINDPAINT_API_KEY}"      }    }  }}

Cursor resolves ${env:...} from the environment it was launched from, so start it from a terminal (cursor .) after exporting the key. Cursor Settings → MCP should list 20 tools. For the skills as well, run npx skills add windpaint-ai/skills in the project. See the Cursor guide.

What the agent can do

The tools fall into four groups. A typical run is list_capabilities → upload_asset → estimate_cost → generate → wait_for_job → download_asset.

Two details matter in practice. The server can't see your disk, so local files go up as base64 and outputs come back as 15-minute signed URLs that the agent fetches with curl. And for slower jobs the agent should submit with wait=false and then call wait_for_job; if a wait times out, the job is still running and calling generate again would bill a second one. The skills tell the agent both things.

A first prompt

Make four 16:9 images of a lighthouse at dusk, long exposure.Estimate the cost first. Save them to ./media.

A lighthouse at dusk, long exposureZ-Image Turbo · seed 11

1. The agent calls list_capabilities to find the live text-to-image models.
2. It calls estimate_cost for image.generate with num_outputs: 4 and asks you to approve the credits.
3. It generates the images with Z-Image Turbo using wait=true; images usually finish in seconds.
4. It downloads each output from its signed URL and saves the files.

Keeping spend under control

• Keep tool approval on for generate and run_workflow. Every other tool is read-only or free.
• Ask for an estimate before batches. estimate_cost validates the request and returns credits plus your available balance without running anything.
• Use a separate project for agent work, so its outputs don't mix with your app's assets and are easy to clean up with retention.
• Failed, canceled and moderated jobs cost nothing, and a timed-out wait doesn't cancel or rebill the job.