MCP Server

Connect Pixa’s AI image and video tools to any MCP-compatible agent or IDE.

The Pixa MCP server exposes Pixa’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 Pixa directly.

Setup

Prerequisites

• A Pixa 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:

https://mcp.pixa.com/mcp

Claude Code

claude mcp add pixa --transport http https://mcp.pixa.com/mcp

Other agents

Pixa MCP is supported in popular MCP clients like ChatGPT, Codex, Cursor, and more. Add https://mcp.pixa.com/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 Pixa 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 Pixa 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 Pixa 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.pixa.com/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 pixa.com/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 pixa.com/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. Pixa 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 *.pixa.com to the list
3. Start a new chat

Need more help?

• API status page
• Contact support