DEV Community

彭英瑞
彭英瑞

Posted on

Wiring MCP image generation into Claude Code and Cursor without local GPUs

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.

Dark-mode coding workstation with dual monitors and warm desk lighting during a late-afternoon setup session

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"
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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}"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 once status turns to success.
  • 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 until status resolves to success or failed.

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.

Printed visual layout sketches and color reference cards arranged beside a laptop on a wooden table

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/.
Enter fullscreen mode Exit fullscreen mode

Three habits keep credit burn low during automated runs:

  1. Treat delivery URLs as temporary. Download returned imageUrls or videoUrls immediately into your local project directory or object storage rather than hardcoding delivery URLs in production code.
  2. Never auto-retry blindly on 402 or safety rejections. If get_image_generation returns failed, inspect the error string first; credits are automatically returned for failed tasks, so tweaking the prompt prevents wasted repeats.
  3. Pass reference images sparingly. Models like Nano Banana 2, GPT-Image-2.6, and Grok Image 2.0 support up to three reference images in this workspace, whereas Wai-SDXL and Z-Image Turbo take text prompts only. Checking referenceImageLimit upfront 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.

Top comments (0)