Assets & Collections

Upload, organize, and search your media assets from MCP.

Assets are the images and videos in your Pixa workspace. Collections let you organize them into groups. Both are fully manageable from the MCP server.

Assets

MCP tools

The assets tool supports list, search, and get actions. Use the upload tool to import from URLs or get a one-time upload URL for local files.

Action	Description
assets (list)	List assets, with optional filters by collection, tag, or status
assets (search)	Search by keyword or semantic similarity
assets (get)	Fetch metadata and a fresh URL for a single asset
upload (url)	Import an image from a public URL
upload (upload_url)	Get a one-time upload URL for a local file

Importing files

Ask the agent to import an image from a URL:

Import this product photo into my workspace: https://example.com/photo.jpg

The agent calls upload with action: "url" and returns the new asset ID:

{
  "id": "ast_abc123",
  "url": "https://assets.pixa.dev/ast_abc123.png",
  "content_type": "image/png"
}

Listing and filtering

List the assets in my "Summer Campaign" collection.

Find product photos tagged "hero" that are ready to use.

The agent calls assets with action: "list" and the appropriate filters (collection_id, tag, or status).

Searching assets

Search uses semantic similarity — describe what you are looking for in natural language:

Find images of red sneakers on a white background.

Semantic search requires a Business tier subscription.

Collections

Collections are named groups of assets. Use them to organize uploads, target batch operations, and keep related assets together.

MCP actions

The collections tool supports list, search, get, and create actions.

Action	Description
collections (list)	List all collections
collections (search)	Search collections by name
collections (get)	Get a collection by ID
collections (create)	Create a new collection

Creating a collection

Create a new collection called "Summer Campaign" and put the images we just generated into it.

The agent calls collections (action: create), then references the new collection ID in subsequent operations.

Common workflows

Organize generated content

Generate 5 product shots, then save them all to a new "Q3 Hero Shots" collection.

The agent calls generate_media to produce the images, collections (create) for the new collection, and includes the collection_id so generated assets land directly in the right place.

Find and process

Find my outdoor furniture photos and remove the background from the best one.

The agent calls assets (search), then edit_image with action: "remove_background" on the chosen result.

You cannot delete assets, collections, or share links via MCP. Use the Pixa web app for deletion.