Cursor · mcp.json · user or project scope

Image generation in Cursor: MCP server setup

Add one mcpServers entry to ~/.cursor/mcp.json — a url and an x-api-key header — and Cursor gains eleven image tools it can call from agent mode. A placeholder rectangle is a small lie you tell yourself at the start of a build and pay for at the end. With an image server connected, Cursor fills those rectangles as it goes: real art, correctly sized, compressed, referenced from the file it just wrote.

Get a free API key Config, both forms
By the imagemcpserver.com teamPublished Updated 3 min setup

Where the file goes

Cursor installs marketplace plugins from the Customize page with one click and OAuth. Anything that is not in the marketplace — this server included — is a JSON entry, and there are two places to put it.

~/.cursor/mcp.json

Every project on this machine. The simplest place to keep your key.

.cursor/mcp.json

This repository only. Committable — if you reference an env var rather than the raw key.

The config, both forms

Cursor speaks HTTP to remote servers directly, so the first form needs no local process at all. The bridge is there for the cases where a version does not pick the remote entry up.

Option A · direct HTTPtry first
{
  "mcpServers": {
    "imagemcp": {
      "url": "https://mcp.imagemcpserver.com/mcp",
      "headers": {
        "x-api-key": "sk-img-gen-your_key_here"
      }
    }
  }
}

no local process — Cursor talks to the endpoint itself

Option B · npx bridge
{
  "mcpServers": {
    "imagemcp": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://mcp.imagemcpserver.com/mcp",
        "--header", "x-api-key:sk-img-gen-your_key_here"
      ]
    }
  }
}

works with any MCP client that can spawn a process

Committing it safely

Cursor resolves ${env:NAME} interpolation inside url and headers, not just in env. That is what makes a project config committable: the file names the variable, each developer exports their own key, and nothing secret enters the repository.

Worth knowing that envFile is a stdio-only option — remote servers do not read one. For a remote entry the variable has to come from the shell environment Cursor inherits, which is also the reason the most common failure is a variable that was exported after Cursor had already started. Checked September 2026.

.cursor/mcp.json · safe to commit
{
  "mcpServers": {
    "imagemcp": {
      "url": "https://mcp.imagemcpserver.com/mcp",
      "headers": {
        "x-api-key": "${env:IMAGEMCP_API_KEY}"
      }
    }
  }
}

Checking it connected

Save the file, reload Cursor, and open the Customize page. The server should be listed with its tools enumerated — that enumeration is the real signal, because a server can appear without having successfully listed anything.

then ask for something small

“Generate a 1:1 placeholder avatar, compress it to WebP, and save it to public/test.webp”

One generation and one compression is two credits of certainty. If the file lands, everything downstream of here is prompt engineering rather than configuration.

What it feels like in agent mode

a single prompt, start to finish

“Build the testimonials section. Use real avatars, not initials — generate them, keep the style consistent, and make sure nothing is over 60 KB.”

list_modelspicks a fast model for six near-identical portraits
multicall → generate_transparent_image × 6one reference image keeps all six in the same style
compress_image × 6WebP at quality 70 — avatars render at 56px
Write TestimonialCard.jsxthe component and the assets land in the same commit

Write the rules once

Cursor follows project rules far more consistently than it follows a preference you mentioned three prompts ago. A short block about images saves you from re-explaining aspect ratios and file sizes on every feature.

  • Name the aspect ratios your layout actually uses.
  • State a maximum file size — it turns compression into a habit.
  • Say when to ask before spending credits.
  • Point at a reference image so a series stays a series.

.cursor/rules/images.mdc

Images come from the imagemcp MCP server.

- Heroes are 21:9, cards are 4:3,
  avatars are 1:1.
- Always compress to WebP before writing
  into /public. Nothing over 200 KB.
- Reuse public/brand/reference.png as a
  referenceImage so styles match.
- Ask before generating more than five
  images in one run.

Teams, marketplaces and allowlists

If you are setting this up on a work machine, there is a layer above your config that can quietly override it, and it is worth knowing before you spend twenty minutes on the JSON.

Team distribution

Admins can share MCP servers with the team, and those appear alongside your own personal and workspace servers rather than replacing them.

MCP allowlist

Enterprise admins can restrict which servers run at all — remote ones approved by URL pattern, local ones by command pattern, with optional per-tool restrictions. An allowlist approves a config; it does not install it.

The practical consequence: a config that works perfectly at home and refuses to connect at work is usually a policy, not a typo. Checked September 2026 — ask an admin to approve the endpoint URL rather than debugging your own file again.

When it will not connect

Five causes, in roughly the order they actually occur.

The JSON is malformed

A trailing comma or an unquoted key stops the whole file parsing, so every server in it disappears at once rather than just the one you edited. If several servers vanished together, this is why.

The environment variable is not where Cursor can see it

Interpolation reads the environment of the process Cursor was launched from. A variable exported in a terminal after Cursor started, or set only in a shell rc file that a GUI launch never sources, will resolve to nothing — and an empty header looks exactly like a bad key.

An admin allowlist has not approved the URL

On team and enterprise plans an admin can restrict which MCP servers run, approving remote servers by URL pattern and local ones by command pattern. A correct config that silently refuses to connect on a work machine is very often this. Checked September 2026.

The key is real but has no credits behind it

The server connects and the tools enumerate, then every call fails. That is an account problem rather than a config problem — check the balance before rewriting the JSON again.

You edited the wrong file

A project .cursor/mcp.json and a global ~/.cursor/mcp.json can both exist. Confirm which one the open workspace is actually reading before concluding the config does not work.

Cursor setup questions

How do I add an MCP server to Cursor?

Two routes. Marketplace entries install from the Customize page with one click and authenticate over OAuth. Anything else — including this server — goes in mcp.json as an mcpServers entry: a url plus a headers object for a remote server, or a command and args for a local one. Save the file and Cursor picks it up.

Where do I put the MCP config in Cursor?

~/.cursor/mcp.json applies to every project on your machine. .cursor/mcp.json inside a repository applies to that project only and can be committed so the whole team gets the same tools — as long as the key itself is referenced through an environment variable rather than pasted in.

Can I commit .cursor/mcp.json without leaking my key?

Yes. Cursor resolves ${env:NAME} interpolation inside the url and headers fields as well as command, args and env, so "x-api-key": "${env:IMAGEMCP_API_KEY}" is safe to commit. Each developer exports the variable in their own shell profile. Note that envFile is a stdio-only option — remote servers do not support it, so shell environment is the route.

Should I use the direct URL or the npx bridge?

Try the direct url + headers form first; Cursor speaks HTTP to remote servers natively and it needs no Node process. Fall back to the mcp-remote command form only if your Cursor version does not pick the remote entry up.

Why is my MCP server not connecting in Cursor?

In rough order: malformed JSON in mcp.json, a key that has not been exported into the shell Cursor actually launched from, or — on a team or enterprise plan — an admin MCP allowlist that has not approved the URL. Open the Customize page and look at whether the server is listed and whether its tools are enumerated.

Do the tools work in Composer and in the chat?

Anywhere the agent can call tools. The practical value shows up in agent mode, where it can generate an asset and edit the file that references it in the same run.

How do I stop it generating images I did not ask for?

Put the rule in your project rules file: only generate images when explicitly asked, and always check the credit balance first. Agents follow written instructions about tools far more reliably than they follow implied ones.

Is there a way to see what it spent?

Yes. Every call from every client lands in the request log in the dashboard with its tool, model and exact credit cost — that is the ledger, not the chat transcript.

Sources & references

Windsurf →GitHub Copilot →All clients