Claude Code · one command · 11 tools
Image generation in Claude Code: MCP setup
One claude mcp add command registers the server and eleven image tools appear in the agent’s tool list. Claude Code can already write the component, the styles and the tests. Connect this server and it can also produce the hero image, cut out the product shot, generate the icon set and compress everything before it commits.
$ claude mcp add --transport http imagemcp \
https://mcp.imagemcpserver.com/mcp \
--header "x-api-key: sk-img-gen-your_key_here"
Added MCP server "imagemcp"
$ claude
> /mcp
imagemcp connected 11 tools
> add a hero image to the pricing page
⏺ generate_image(aspectRatio: "21:9") …
⏺ compress_image(quality: 80) …
⏺ Write(public/hero-pricing.webp)Two ways in. Pick one.
Both expose the same operations and bill the same credits. The difference is whether the tools arrive over the Model Context Protocol or as a command the agent runs.
MCP server
recommendedTools appear natively in the agent’s tool list with their full schemas, so it knows the parameters without being told. Add once, available in every session.
claude mcp add --transport http imagemcp \
https://mcp.imagemcpserver.com/mcp \
--header "x-api-key: $IMAGEMCP_API_KEY"Run it in your terminal rather than inside a claude session — you are configuring the server before starting a conversation. It lands at local scope unless you say otherwise; see below.
Skill & CLI
A skill directory plus a zero-dependency Node CLI that prints structured JSON. Nothing to keep running, and it works anywhere the agent can execute a shell command — including CI.
npx skills add imagemcp/skill
export IMAGEMCP_API_KEY=sk-img-gen-…
node imagemcp.js generate \
--prompt "isometric server rack" \
--aspect 4:3Scopes: where it actually gets written
This is the part that trips people up. The default is local scope — private to you and only active in the directory you ran the command from. A server you added last week appearing to have vanished in a different repository is almost always this, not a broken config.
| Scope | Flag | Written to | Available to |
|---|---|---|---|
| local | default | ~/.claude.json, under this project | Only you, only this project |
| project | --scope project | .mcp.json in the project root | Everyone who clones it — after each approves it |
| user | --scope user | ~/.claude.json, top-level mcpServers | Only you, every project |
Project scope needs approving
Committing .mcp.json shares the server, but Claude Code will not trust a checked-in server definition on its own. Each teammate sees it as pending until they approve it once. That is a feature — a repository should not be able to add tools to your agent silently.
Scope is fixed at add time
There is no command to move a server between scopes. Remove it and add it again with the scope you wanted. claude mcp get imagemcp tells you which scope currently holds it.
Reading the connection status
claude mcp list is the fastest diagnostic, and its statuses are more specific than they look — each one points at a different fix. Inside a session, /mcp does the same job.
✔ ConnectedReady. Tools are listed and callable.
! Connected · tools fetch failedThe server answered but could not list tools. Run claude mcp get imagemcp for the detail.
! Needs authenticationReachable but unauthenticated — usually a missing or malformed --header.
✘ Failed to connectNo response. Check the URL first, then the network.
⏸ Pending approvalA project-scoped server you have not approved yet. Run claude and approve it.
⊘ Disabled for this projectTurned off in the project’s disabledMcpServers list. Re-enable with /mcp.
Verified against claude mcp --help and the Claude Code docs, September 2026. One thing worth knowing that is easy to miss: every connected server costs context, because its tool names and instructions load into each session. Removing servers you have stopped using is free performance.
What changes in day-to-day work
The interesting part is not that the agent can generate an image. It is that generating one stops being a context switch — the asset appears in the same turn as the code that uses it.
“Build the marketing page from this brief.”
Without image tools
Ships with grey placeholder boxes and a TODO for design.
With them connected
Generates the hero, the three feature illustrations and the OG image, compresses them to WebP and references them from the JSX.
“Our icons are inconsistent — fix them.”
Without image tools
Suggests an icon library and leaves the migration to you.
With them connected
Generates a matching SVG set with one style prompt, writes each as a component, and deletes the mismatched PNGs.
“Every product image in /public is a 4MB PNG.”
Without image tools
Explains what a WebP is.
With them connected
Runs a batch compression over the folder, rewrites the references, and reports the before-and-after page weight.
Keeping an autonomous agent honest
An agent with a spending tool needs the same treatment as an agent with a deploy tool. These are the three habits worth putting in your project instructions.
- 1
Check the balance first
get_user_info is free. Telling the agent to call it before a batch means it can stop rather than fail halfway through forty images.
- 2
Draft cheap, finish expensive
Iterate on a fast model, then re-run the approved prompt on a premium one. Upscaling and compression happen once, at the end.
- 3
Read the log afterwards
Every call is recorded with its cost in the dashboard. A run that cost more than expected is a question you can answer with data.
drop this in CLAUDE.md
## Images Image assets come from the imagemcp MCP server. Before generating a batch, call get_user_info and stop if credits are low. - Draft on a fast model, finalise on a premium one only after I approve. - Always compress to WebP before writing an image into /public. - Never commit a PNG over 500 KB.
Claude Code questions
How do I add an MCP server to Claude Code?
Run claude mcp add --transport http <name> <url> in your terminal, outside a claude session, adding --header for any auth the server needs. Then run claude mcp list and check the server shows a connected tick before you start a session.
What scope does claude mcp add use by default?
Local scope, which is private to you and active only in the project you ran the command in. That is why a server added in one repository appears to vanish in another. Use --scope user to register it once for every project, or --scope project to share it with the team.
MCP server or the skill — which should I use?
The MCP server if you want the tools available in every session automatically. The skill and CLI if you prefer the agent to shell out to a command, which is also what you want on machines where you would rather not run a bridge process.
Can I scope the server to one project?
Yes. Adding it with project scope writes a .mcp.json in the repository so everyone who clones it gets the same server — though each teammate has to approve it once before it connects, since Claude Code does not trust a checked-in server definition automatically.
Should the API key go in the repo?
No. Keep the key in your environment and reference it, or add the server at user scope so the credential never enters a file that gets committed. A committed key should be revoked from the dashboard immediately.
Will the agent burn credits without asking?
It calls tools the same way it calls any other. get_user_info and list_models are free, so a well-prompted agent can check the balance before it starts. Every call also lands in the request log with its exact cost, so nothing is invisible after the fact.
Does it work in a headless or CI run?
Yes — the CLI is a plain Node script that prints JSON and reads the key from IMAGEMCP_API_KEY, so a non-interactive run can generate assets exactly like an interactive one.