> ## Documentation Index
> Fetch the complete documentation index at: https://pixelcut.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Connect Pixelcut's AI image and video tools to any MCP-compatible agent or IDE.

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](https://www.pixelcut.ai))
* An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)

### Claude

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

```
https://mcp.pixelcut.ai/mcp
```

### Claude Code

```bash theme={null}
claude mcp add pixelcut --transport http https://mcp.pixelcut.ai/mcp
```

### 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

| Tool            | Actions                                  | Description                                                                                      |
| --------------- | ---------------------------------------- | ------------------------------------------------------------------------------------------------ |
| **edit\_image** | `remove_background`, `upscale`, `expand` | AI image editing with batch support. Accepts a single image or an array for parallel processing. |

### Generation

| Tool                | Actions                              | Description                                                                                                                     |
| ------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| **generate\_media** | --                                   | Generate images or videos from a text prompt. Requires a `model` ID (use `models` to find one). Returns a `job_id` immediately. |
| **models**          | `list`, `search`, `get`, `recommend` | Browse and search available AI models. Call `list` before generating to find valid model IDs.                                   |

### Asset management

| Tool             | Actions                                       | Description                                                                      |
| ---------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
| **assets**       | `list`, `search`, `get`                       | Browse, search, and fetch details for your media assets.                         |
| **upload**       | `url`, `upload_url`                           | Import an image from a public URL, or get a one-time upload URL for local files. |
| **collections**  | `list`, `search`, `get`, `create`             | Organize assets into named groups.                                               |
| **share\_links** | `list`, `get`, `create`, `update`, `contents` | Create shareable links to asset selections or collections.                       |

### Workflows

| Tool                  | Actions                                                                                 | Description                                             |
| --------------------- | --------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| **pipelines**         | `list`, `search`, `get`, `run`, `list_runs`, `get_run`, `cancel_run`, `list_node_types` | Inspect and run reusable multi-step workflows.          |
| **display\_pipeline** | --                                                                                      | Render an interactive node graph preview of a pipeline. |

### Account and jobs

| Tool                 | Actions                    | Description                                                                                                       |
| -------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **account**          | `credits`, `usage_history` | Check your credit balance and view usage history.                                                                 |
| **get\_job\_status** | --                         | Poll the status of async jobs (generation, edits). Supports `sync: true` to wait up to 25 seconds for completion. |

### Display

| Tool        | Actions | Description                                                                          |
| ----------- | ------- | ------------------------------------------------------------------------------------ |
| **display** | --      | Render a visual gallery of assets or collections. Only available in rich UI clients. |

***

## 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](/developer-guide/core-concepts/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](https://www.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/settings](https://www.pixelcut.ai/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?

* [API status page](https://status.pixelcut.ai)
* [Contact support](/user-guide/troubleshooting/contact-support)