When an AI coding agent builds a landing page or tests a game prototype, hitting a missing placeholder asset breaks the flow. Setting up MCP image generation over a remote Streamable HTTP server lets terminal agents such as Claude Code and editors like Cursor request images and short videos directly during a build without provisioning local GPU drivers.
Instead of downloading multi-gigabyte checkpoints or wiring custom Python wrappers around third-party REST calls, a single endpoint handles model discovery, task submission, and status polling across nine image and video models. Everything shares one credit balance, and failed generation tasks automatically refund reserved credits.
Why remote Streamable HTTP beats local stdio wrappers
Early MCP setups relied heavily on local stdio scripts. Every developer on a project had to clone a wrapper repository, maintain Python or Node dependencies, and keep SDK versions aligned whenever a provider updated model parameters.
A remote Streamable HTTP endpoint shifts that maintenance out of the repo. Your editor or terminal agent connects directly to https://imagifly.net/api/mcp with a standard bearer token header. When a team member opens the project, the client reads environment interpolation such as ${IMAGIFLY_API_KEY}, keeping API credentials out of git history.
There is also a practical cost advantage when prototyping. Creating an account grants 10 free credits each day you visit while signed in, with no credit card required, so you can validate tool calls before committing to a paid plan or batch pack.
Configuring Claude Code and Cursor in two minutes
Before adding the configuration, generate an API key (imf_...) from the developer console and export it in your shell profile as IMAGIFLY_API_KEY. Never commit raw keys into .mcp.json or editor configs.
For Claude Code in macOS or Linux, register the server with one command:
claude mcp add --transport http imagifly https://imagifly.net/api/mcp \ --header "Authorization: Bearer $IMAGIFLY_API_KEY" On Windows PowerShell, pass the PowerShell environment variable syntax instead:
claude mcp add --transport http imagifly https://imagifly.net/api/mcp ` --header "Authorization: Bearer $env:IMAGIFLY_API_KEY" If you want project collaborators to inherit the server definition, add a .mcp.json file at the repository root:
{ "mcpServers": { "imagifly": { "type": "http", "url": "https://imagifly.net/api/mcp", "headers": { "Authorization": "Bearer ${IMAGIFLY_API_KEY}" } } } } One easy gotcha: Claude Code requires "type": "http" whenever a url field is present. Omitting "type" triggers a config error. The exact setup steps for Codex, Cursor, OpenClaw, and other clients are documented in the remote MCP setup guide.
After restarting the agent or running /mcp, verify the server registers cleanly:
claude mcp list claude mcp get imagifly If the client reports a healthy connection yet displays zero tools, check your Authorization header formatting. Unauthenticated handshakes often connect at the transport layer while exposing no capabilities.
How remote MCP image generation handles async jobs
Media creation is fundamentally slower than text completion. Image tasks typically finish in 10 to 60 seconds, while video renders can take several minutes. Expecting an agent tool call to block a single HTTP request until a 1080P clip completes leads to dropped connections and client timeouts.
To stay resilient, MCP image generation splits work into two explicit phases: submission and polling. When everything is wired properly, the server exposes six focused tools:
-
list_image_models— fetches active image models, credit prices, and reference-image limits. -
generate_image— queues a text-to-image or reference-image task with aspect ratio, quality tier, and optional reasoning steps. -
get_image_generation— polls an image task ID and returns output URLs oncestatusturns tosuccess. -
list_video_models— reads available video models, aspect ratios, sizes, and supported clip durations. -
generate_video— submits text-to-video, reference-to-video, or first/last-frame jobs. -
get_video_generation— polls a video job ID untilstatusresolves tosuccessorfailed.
Notice why list_image_models and list_video_models matter for agent reliability. Model parameters shift as engines update: Seedance 2.0 supports 5 to 15 seconds while 2.5 extends to 30 seconds, MiniMax H3 supports r2v, fl2v, and t2v formats, and Qwen Image Edit targets image editing with up to three references. Letting the agent query the live catalog prevents hallucinated aspect ratios or invalid duration flags.
You can inspect the schema and parameter mappings for the six MCP image and video tools directly before writing custom agent instructions.
Keeping agent prompts predictable in real builds
Once connected, the cleanest way to keep an agent from looping endlessly or guessing sizes is to write explicit task constraints into your prompt or CLAUDE.md / .cursorrules:
First call list_image_models to pick a model suited for small legible UI posters. Then call generate_image with ratio "16:9", poll get_image_generation every 3 seconds until status is "success" or "failed", and download the resulting file into ./public/assets/. Three habits keep credit burn low during automated runs:
- Treat delivery URLs as temporary. Download returned
imageUrlsorvideoUrlsimmediately into your local project directory or object storage rather than hardcoding delivery URLs in production code. - Never auto-retry blindly on
402or safety rejections. Ifget_image_generationreturnsfailed, inspect theerrorstring first; credits are automatically returned for failed tasks, so tweaking the prompt prevents wasted repeats. - Pass reference images sparingly. Models like
Nano Banana 2,GPT-Image-2.6, andGrok Image 2.0support up to three reference images in this workspace, whereasWai-SDXLandZ-Image Turbotake text prompts only. CheckingreferenceImageLimitupfront stops fallback surprises.
For developers already living inside Claude Code or Cursor, moving asset creation into the same terminal session removes the context switch of exporting files manually. Add the Streamable HTTP block, set your key in the environment, and let the agent pull live model limits before it generates a single pixel.


