ImageStep

@imagestep/mcp

The image pipeline for agents: presets + assets + jobs, as MCP tools. Images never enter the context window — every tool takes and returns asset references (ids, sizes, public URLs).

Every tool declares an outputSchema: the keys it can answer with in structuredContent, all optional (which ones come back depends on the mode — a finished job, a wait that ran out, a dry run, a synchronous result, a refusal).

Inputs are asset_ids, urls (public http(s), fetched and ingested by the service — never downloaded by this server) or — when the server runs on your machine over stdio — file_paths. Every tool that spends money has dry_run (exact price, nothing created or uploaded — asset_ids are priced as themselves, file_paths / urls by how many) and returns structured errors with retryable, param and the service's requestId (quote it when reporting a failure), so a parameter mistake is refused before any credit is charged.

file_paths are files on your machine, and the agent naming them may be following an instruction it read in a page or a mail, so the server checks each one before reading a byte of it:

• a path through a hidden file or folder — any name starting with . (~/.ssh, ~/.imagestep, .env) — is refused, also when a symlink leads there; ./ and ../ are resolved first;
• when your client declares MCP roots, only files under them are read; when it declares none, IMAGESTEP_MCP_FILE_ROOTS (folders separated like PATH) does the same job; with neither, any other folder is readable;
• roots are compared on real paths, so a symlink inside a root cannot lead out of it.

A refusal is invalid_param on file_paths and names the path by its index, never its contents. And a job over local files does not publish its outputs unless the call says publish: true — publish defaults to on only when the inputs are asset_ids or urls (and for generate).

The write tools (generate · transform · run_preset · save_preset · send_feedback) take an optional idempotency_key. An MCP client that times out makes the agent call the tool again; with the same key and the same arguments that second call returns what the first one answered — the job it created, the preset it saved — instead of submitting (and charging for) another. The same key with different arguments is refused with idempotency_key_reuse. Without a key, every call is a new submission.

Every tool carries MCP annotations, the hints a client reads to decide what needs your confirmation: job_status and search_assets are readOnlyHint; the write tools are not idempotent (without a key), and none is destructiveHint: every job writes new assets and never overwrites the one it read.

transform has two modes and the agent does not choose

Synchronous when all of these hold: exactly ONE local file or URL, a deterministic op, and wait: true. Nothing is stored in the account — no asset id exists afterwards, because none was created. Sub-second, and the account stays clean.

Where the result goes depends on which of the two servers you are talking to, because the two do not share a filesystem:

Both carry mimeType, width and height, so the next tool does not have to guess. The hosted answer is a URL for the obvious reason and it took a bug to notice it: your agent is not on the machine the server runs on, so a path into that container's /tmp is an answer it cannot read. Under the hood that is the API's own ?response=url, which writes the bytes to a short-lived temp object — still nothing in your asset catalogue.

As a job for everything else: several images, asset_ids, any AI op, or wait: false. You get asset ids and public URLs, plus progress, cancellation and webhooks.

Which ops may go the first way is read from GET /api/v1/ops (syncEndpoint), never hard-coded — a deterministic op added to the API is fast here without this package changing. If the catalogue cannot be reached, the job path is used: slower is a better failure than wrong.

A urls input is judged the same on both paths: it must resolve to a public address, and it is refused here — before anything leaves the process — not only by the service that would fetch it. One input never gets two answers because of which transport happened to carry it.

Neither mode ever returns image bytes. An image in the context window is tokens the agent pays for and cannot read; the answer is always a path, an id or a URL.

Resources

The catalogue resources exist because an MCP-only client (Claude Desktop) cannot curl the API or open the console, and "never invent a parameter" is a rule it can only follow if it can read them. transform also carries a one-line-per-op summary — name(type=default), plus the values a parameter takes when the catalogue lists them, what a required one means, and for an AI op the model's own parameters object — generated from the same catalogue; when that could not be read, it falls back to a built-in summary and says so. All five are read live: a read that cannot reach the service fails rather than answering from a copy.

imagestep://agent-guidelines is the operating contract — read the op catalogue instead of carrying a list, price with a dry run before spending, branch on retryable rather than the status code, keep a batch consistent with a preset, and report a missing capability instead of working around it. It is a resource rather than a tool because a tool is something an agent decides to call and the rules are something it should have read, and it is fetched from the service on every read, so a copy of this package released months ago still serves today's contract.

Connect

Get an API key at https://imagestep.dev/keys?utm_source=npm&utm_medium=mcp-readme.

Claude Desktop (claude_desktop_config.json) — local, can upload files from disk:

{

"mcpServers": { "imagestep": { "command": "npx", "args": ["-y", "@imagestep/mcp"], "env": { "IMAGESTEP_API_KEY": "is_sk_…" } } } }

Cursor (.cursor/mcp.json) — same shape:

{ "mcpServers": { "imagestep": { "command": "npx", "args": ["-y", "@imagestep/mcp"], "env": { "IMAGESTEP_API_KEY": "is_sk_…" } } } }

Claude Code — local:

claude mcp add imagestep -e IMAGESTEP_API_KEY=is_sk_… -- npx -y @imagestep/mcp

Remote (any client that speaks Streamable HTTP) — nothing to install:

claude mcp add --transport http imagestep https://mcp.imagestep.dev/mcp --header "Authorization: Bearer is_sk_…"

The remote server is stateless: each request is served by a fresh server bound to the API key in the Authorization header (Bearer or ApiKey). file_paths is disabled there; pass urls or asset_ids. It logs one JSON line per request on stdout: the JSON-RPC method, the tool name of a tools/call, the clientInfo an initialize reports, your key's prefix (the 12 characters the console shows — never the key), whether the key is valid, the HTTP status and the duration. Never a tool's arguments or your prompt. The validity comes from a side request to the API (3 s timeout, not counted as a use of the key), and the answer, valid or not, stands for five minutes. The handshake never waits for it. A request that can call the API on your key (a tool call, a resource read) does, when the server has not seen that key yet, so a wrong key is turned down there with the same unauthorized error the API gives and never reaches the API. An address whose keys turned out invalid 20 times in a minute gets HTTP 429 with Retry-After for any key the server has not seen yet, until the minute is up; a key it already knows to be good keeps working.

The remote server waits at most 90 s per tool call (wait_seconds above that is clamped; the default there is 90). It answers each call as one JSON body, so nothing reaches your client until the tool returns, and Cloudflare's edge drops a response that has not started after 100 s — you would get an HTML 524 with no job id while the job kept running. Past 90 s you get the job handle with timedOut: true instead; poll job_status. Over stdio the wait is what you ask for (default 180 s, max 600 s).

Try it

Upload ./product.jpg, remove the background, upscale it 2×, and give me the URL.

The agent calls transform (remove_bg, file_paths), then transform (upscale, asset_ids = the previous output, `parameters: