MCP server

Cutstack as tools for Claude, Cursor, Claude Code and any client that speaks the Model Context Protocol. The same API, driven by an agent instead of your code.

The server is an npm package, @cutstack/mcp. It runs on your machine next to the client, talks to it over stdio, and calls /v1 with your API key. It holds no logic of its own: every tool is one or two of the calls documented on this site, so what the agent can do is exactly what the API can do, including reading photos from a folder on your disk and writing the ZIP back to it.

Setup

Node.js 18 or newer, and a key from API keys. The key lives in the server’s environment; no tool accepts it as an argument, so the model never sees it.

{
  "mcpServers": {
    "cutstack": {
      "command": "npx",
      "args": ["-y", "@cutstack/mcp"],
      "env": { "CUTSTACK_API_KEY": "csk_live_..." }
    }
  }
}

claude mcp add cutstack -e CUTSTACK_API_KEY=csk_live_... -- npx -y @cutstack/mcp

Cursor and other clients take the same JSON as Claude Desktop. Two optional variables: CUTSTACK_BASE_URL to point at another server, and CUTSTACK_MCP_DIR for where downloads land when a tool is called without a path (default: a cutstack-mcp folder in the system temp directory).

How the agent works with it

A batch is three steps, like the API: create_job, add_images, start_job. Pictures never enter the conversation. Photos go up from disk or by link, results come back as paths on disk, and every tool answers with a short line plus structured data: counts, what needs a decision, where the file is. The agent follows a running batch with wait_job, which holds up to a minute and returns when something changes, instead of polling.

When the batch finishes, review_queue lists only the photos worth a look: failed ones and those the automatic check flagged, with the reason, the area and a resource URI for a thumbnail of at most 512 px. That thumbnail is the one exception to the no-pixels rule: an agent with vision reads it to decide whether a flagged photo is really broken, then re-runs it, reports it, drops it or keeps it.

Credits and the confirm rule

The two tools that send a whole batch to the model, start_job and continue_job, do nothing unless they are called with confirm: true. Without it the answer states how many photos would run, how many credits that reserves and the current balance, so the agent can put the question to you. Every other tool that charges (retry_item, retry_items) says the cost in its description and the amount charged in its answer. Flagged photos are refunded as always, and changing settings never costs anything.

The agent’s first run on a new catalogue should be a sample: start_job with sample: 10, a look at the review queue, then continue_job for the rest. The process-catalog prompt bundled with the server does exactly that.

Tools

Resources and prompts

Two prompts appear in the client’s menu: process-catalog (a folder, a preset, a background: create, sample, continue, review, export) and review-flagged (go through the queue of one batch, thumbnail by thumbnail, and decide).

Same rules as the API

• Up to 200 photos per batch, two batches running at once per account, results kept for two hours (Limits).
• Credits are spent plan first, then bought ones (Credits).
• Errors carry the API’s codes and one sentence on what to do next (Errors), so the agent can act on NO_CREDITS or TOO_MANY_ACTIVE without guessing.
• Folders are read one level deep, JPEG, PNG, WebP and ZIP; other files are reported, not uploaded.

Source and issues: the package is published from the Cutstack repository under mcp/. Questions go to the Agents & API form. The OpenAPI description at https://trycutstack.com/v1/openapi.json remains the contract for both doors.

Next: Reference. The OpenAPI spec, every endpoint, MCP.