MCP Reference

This page is written for AI agents and HTTP clients using the Cutout Magic MCP server. It lists every parameter, cost, and failure mode — nothing else.

• Server: https://cutoutmagic.com/api/mcp
• Transport: MCP Streamable HTTP, JSON responses (a Mcp-Session-Id header routes requests to an established session; a request without one starts a new initialize)
• Auth: send Authorization: Bearer cmk_... on the initialize request. Create the key in the web app under Settings → API keys. Keys are revocable there at any time.
• Protocol version negotiated at initialize: 2025-06-18

Authentication rules

• The API key is verified on initialize; the server remembers the session after that.
• A key may hold several MCP sessions; still use one key per client so revoking one doesn't kill the rest.
• An API key is required — without one, initialize returns HTTP 401 with a JSON-RPC error body, and unknown session IDs return HTTP 404. The key is verified on every request: a revoked or deleted key kills any live session (401 on the next call).
• An MCP session gives the same access as the browser session that created the key.

Tools

list_images

Lists the user's image folders. No cost.

Output: JSON array of folders. Each folder has id, source and derivatives; every image has a url that can be viewed or downloaded directly.

upload_image

url (string, required) — an http(s):// URL or a data: URL of an image.

Adds the image to the library (free). The returned JSON has image.id — use that as folder for all other tools.

remove_background

folder (string, required), filename (string, required).

Keeps the main subject, removes the rest of the image. Cost: 5 credits.

label_image

folder, filename (strings, required).

Detects objects and returns labels with bounding boxes (values 0-1). Cost: 2 credits.

crop_image

folder, filename (strings, required), boundingBox (required): { x, y, width, height }, each a number 0-1.

No cost. Returns the cropped derivative's url and path.

extract_object

• folder, filename (strings, required)
• object (string OR { label?: string, boundingBox: { x, y, width, height } }, required) — a label from label_image, or a label plus bounding box
• backgroundColor (string, optional) — e.g. transparent
• model (string, optional) — low (default), medium, high

Cuts the object out of the image. Cost: low 20, medium 30, high 50 credits.

remove_object

• folder, filename (strings, required)
• object (string, required) — the label of the object to remove
• model (string, optional) — low (default), medium, high

Removes the object and inpaints behind it. Cost: low 20, medium 30, high 50 credits.

get_favorites

Lists favorited images. No cost.

Error behavior

• Image not found: tool result isError: true, message tells the agent to call list_images for valid folder/filename pairs.
• Insufficient credits: tool result isError: true with the credit cost in the message. The transaction is aborted before any charge.
• Duplicate work (a second remove_background on the same image): tool result isError: true and the charge is removed — no double charge for the same result.
• Other processing failures: the request errors out (JSON-RPC error), and the charge is left pending for manual investigation — no automatic refund.
• Unknown or expired session ID: HTTP 404.

Policy

• Uploaded images and all tool outputs are processed as described in the privacy policy and terms of use.
• Content rules in the terms apply equally to actions taken through MCP keys.