Skip to main content
The Pixelcut MCP server exposes Pixelcut’s full suite of AI editing, generation, and asset management tools via the Model Context Protocol. This lets any MCP-compatible client — Claude Desktop, Claude Code, Cursor, Windsurf, or custom agents — use Pixelcut directly.

​
Setup

​
Prerequisites

  • A Pixelcut account (sign up here)
  • An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

​
Claude

  1. Go to Settings → Connectors → Add Custom Connector
  2. Enter the server URL:

​
Claude Code

​
Other agents

Pixelcut MCP is supported in popular MCP clients like ChatGPT, Codex, Cursor, and more. Add https://mcp.pixelcut.ai/mcp as a remote MCP server in your agent or editor’s MCP settings. Refer to your client’s documentation for the exact config location.

​
Verify the connection

Once configured, ask your agent something like:
“Check my Pixelcut credit balance.”
If the agent calls the account tool and returns your balance, the connection is working.

​
Available tools

The MCP server provides 12 tools. Tools that support multiple operations use an action parameter.

​
Editing

​
Generation

​
Asset management

​
Workflows

​
Account and jobs

​
Display

​
Examples

​
Remove a background

“Remove the background from this product photo.”
The agent calls edit_image with action: "remove_background" and returns the result with a transparent background.

​
Batch upscale

“Upscale all the images in my ‘Product Shots’ collection to 4x.”
The agent calls assets to list the collection contents, then edit_image with action: "upscale", scale: "4", and an array of asset IDs.

​
Generate an image

“Generate a studio product photo of a water bottle on a marble countertop.”
The agent first calls models (action: list, type: image) to find a model, then calls generate_media with the chosen model ID and prompt. The result is an async job — the agent polls get_job_status or the UI widget polls automatically.

​
Expand for a banner

“Expand this square image to 16:9 for a website banner.”
The agent calls edit_image with action: "expand" and aspect_ratio: "16:9".

​
Run a pipeline

“Run my ‘Hero Banner’ pipeline on these three product images.”
The agent calls pipelines (action: get) to inspect the pipeline, then pipelines (action: run) with the input images mapped to the correct node IDs.

​
Share results

“Create a share link with the images I just generated.”
The agent calls share_links with action: "create" and the asset_ids from the generation results.

​
Limitations

  • Credit consumption. Generation and editing operations consume credits from your Pixelcut account. Check your balance with account (action: credits).
  • Temporary URLs. Result URLs expire. Always use asset_id for downstream operations (chaining edits, organizing, sharing). Use assets (action: get) to get a fresh URL when needed.
  • Async generation. generate_media returns immediately with a job_id. The images/videos are not ready until the job completes. In text-only clients, use get_job_status with sync: true to wait.
  • Semantic search requires Business tier. The assets (action: search) tool requires a Business subscription.
  • Rate limits. The MCP server is subject to the same rate limits as the REST API.
  • No destructive operations. You cannot delete assets, collections, or share links via MCP. Use the Pixelcut web app for deletion.
  • Share link constraints. When creating a share link, provide either asset_ids or collection_id — not both.

​
Troubleshooting

​
Tools not appearing in the client

  1. Restart your MCP client after changing the config.
  2. Verify you’ve added https://mcp.pixelcut.ai/mcp as the server URL.
  3. Check that you’ve completed the OAuth login when prompted.

​
”Unauthorized” or 401 errors

Your session may have expired. Restart the MCP client to trigger a new OAuth login. If using an API key, verify it is valid — generate a new one at pixelcut.ai/developer-settings.

​
Generation jobs stuck in “running”

Some models take longer than others. Use get_job_status with sync: true to wait up to 25 seconds. For video generation, jobs can take several minutes — poll periodically rather than using sync mode.

​
”Insufficient credits” errors

Check your balance with account (action: credits). Purchase more credits or upgrade your plan at pixelcut.ai/developer-settings.

​
”Upgrade required” errors

Some features (like semantic search) require a higher subscription tier. The error response includes an upgrade_url — follow it to upgrade your plan.

​
Image input not recognized

When passing images to tools, use one of these formats (in order of preference):
  1. Pixelcut asset ID — e.g., ast_abc123
  2. Public HTTP/HTTPS URL — e.g., https://example.com/photo.jpg
  3. Local file — first call upload (method: upload_url) to get an upload URL, run the returned curl command, then pass the resulting asset_id

​
File uploads failing in Claude

Claude blocks outgoing network connections by default. To enable file uploads via the upload tool:
  1. Go to Settings → Capabilities → Network Egress → Additional allowed domains
  2. Add *.pixelcut.ai to the list
  3. Start a new chat

​
Need more help?