What the MCP server does
The Model Context Protocol (MCP) lets an AI assistant call external tools. The Cutout Labs MCP server gives an assistant two tools: remove_background, which removes the background from an image and returns or saves the cutout, and get_quota, which reports how many free calls remain today for your API key.
There are two ways to run it. The hosted server at https://api.cutoutlabs.com/mcp uses Streamable HTTP, takes an image URL or base64 data, and returns the result inline. The local package @cutoutlabs/mcp runs on your computer, reads image files from disk, and saves the cutout next to the original. Both use the same API key and the same daily free quota.
| Hosted server | Local package | |
|---|---|---|
| Connection | https://api.cutoutlabs.com/mcp (Streamable HTTP) | npx -y @cutoutlabs/mcp (stdio) |
| Image input | image_url or image_base64 | input_path (local file) or image_url |
| Result | Returned to the assistant as an image | Saved to disk; the assistant gets the file path |
| Output sizes | preview, medium (default), hd | preview, medium, hd, full (default) |
| Best for | Chat clients and remote agents working with URLs | Coding agents and assistants that edit files in a project |
Get an API key
Create a free key on the API page. The key is sent as an X-Api-Key header or as Authorization: Bearer. During launch the API is free with a daily per-key quota that resets at 00:00 UTC. Keep the key in your MCP client's secret or environment settings rather than in a file you commit to a repository.
Connect your MCP client
Each client stores MCP servers in a JSON configuration file. Replace YOUR_KEY with your API key, save the file, and restart or reload the client so it lists the new tools.
| Client | Where | Configuration |
|---|---|---|
| Claude Desktop (local package) | claude_desktop_config.json, opened from Settings, Developer, Edit Config | { "mcpServers": { "cutoutlabs": { "command": "npx", "args": ["-y", "@cutoutlabs/mcp"], "env": { "CUTOUTLABS_API_KEY": "YOUR_KEY" } } } } |
| Cursor (hosted server) | .cursor/mcp.json in the project, or ~/.cursor/mcp.json for all projects | { "mcpServers": { "cutoutlabs": { "url": "https://api.cutoutlabs.com/mcp", "headers": { "Authorization": "Bearer YOUR_KEY" } } } } |
| VS Code (hosted server) | .vscode/mcp.json in the workspace | { "inputs": [{ "type": "promptString", "id": "cutoutlabs-key", "description": "Cutout Labs API key", "password": true }], "servers": { "cutoutlabs": { "type": "http", "url": "https://api.cutoutlabs.com/mcp", "headers": { "Authorization": "Bearer ${input:cutoutlabs-key}" } } } } |
Ask the assistant to use it
You do not need to name the tool. Describe the image and what you want, and the assistant chooses remove_background and fills in the options. Examples that map directly to the tool options:
- Remove the background from ./images/shoe.jpg and save it as a transparent PNG.
- Remove the background from this product photo URL, crop it to the product, and put it on a white background.
- This photo shows a hand holding a bottle. Keep only the bottle in the area from 30% 10% to 70% 90% of the image.
- Remove the background from the portrait and clean the coloured fringe from the hair.
- How many free background removals do I have left today?
remove_background options
Provide exactly one image source. Every other option is optional; with none, you get a transparent PNG of the main subject.
| Option | Values | Effect |
|---|---|---|
| size | preview, medium, hd; full in the local package | Output resolution: about 0.25 MP, 1.5 MP, or 4 MP; full returns the largest available size |
| format | png, webp, jpg | Defaults to png. JPG has no transparency |
| bg_color | A hex color such as ffffff, or a color name | Puts the subject on a solid color instead of transparency |
| crop | true or false | Crops the output to the subject |
| roi | x1 y1 x2 y2 in pixels or percent | Keeps only the subject inside that box, useful when a hand or second object is in frame |
| clean_edges | true or false | Removes coloured fringes from the old background in hair, fur, and soft edges |
| output_path and overwrite | Local package only | Choose where the file is saved and whether to replace an existing file |
Limits and troubleshooting
Inputs can be up to 12 MB. The hosted server returns results inline and rejects a result larger than 6 MB; ask for medium or hd instead of a larger output. Requests are limited per key per minute, and the daily free quota resets at 00:00 UTC.
| Message | Cause | Fix |
|---|---|---|
| Missing API key | The client did not send X-Api-Key or Authorization: Bearer | Check the header or env value in the client configuration and reload it |
| CUTOUTLABS_API_KEY is not set | The local package started without the environment variable | Add CUTOUTLABS_API_KEY to the server's env block |
| The result is too large to return over MCP | The hosted server's inline result limit | Use size medium or hd, or use the local package to save full-size files |
| Daily free quota reached | The key has used today's free calls | Wait for the 00:00 UTC reset or request a higher limit from the API dashboard |
| Already exists | The local package will not overwrite a file by default | Pass overwrite: true or a different output_path |