Setup
Prerequisites
- A Pixa account (sign up here)
- An MCP-compatible client (Claude Desktop, Claude Code, Cursor, etc.)
Claude
- Go to Settings → Connectors → Add Custom Connector
- Enter the server URL:
Claude Code
Other agents
Pixa MCP is supported in popular MCP clients like ChatGPT, Codex, Cursor, and more. Addhttps://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 anaction 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_idfor downstream operations (chaining edits, organizing, sharing). Useassets(action:get) to get a fresh URL when needed. - Async generation.
generate_mediareturns immediately with ajob_id. The images/videos are not ready until the job completes. In text-only clients, useget_job_statuswithsync: trueto 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_idsorcollection_id— not both.
Troubleshooting
Tools not appearing in the client
- Restart your MCP client after changing the config.
- Verify you’ve added
https://mcp.pixa.com/mcpas the server URL. - 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. Useget_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 withaccount (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 anupgrade_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):- Pixa asset ID — e.g.,
ast_abc123 - Public HTTP/HTTPS URL — e.g.,
https://example.com/photo.jpg - Local file — first call
upload(method:upload_url) to get an upload URL, run the returnedcurlcommand, then pass the resultingasset_id
File uploads failing in Claude
Claude blocks outgoing network connections by default. To enable file uploads via theupload tool:
- Go to Settings → Capabilities → Network Egress → Additional allowed domains
- Add
*.pixa.comto the list - Start a new chat