Epox Docs
Open app

Catalogue tools

MCP reference for reading products, generated assets, collections, and the image and video models — plus the two workspace resources — over the Epox MCP server.

9 min read Updated 2026-10-02

Use these tools to read your products, generated assets, collections, and the models you can generate with. Each tool has its description on the left and a request and response example on the right.

Before you start

Products

epox_list_products

List products in the connected workspace.

limit (1–50, default 20), cursor, and search are all optional. List rows name each source photo by id only; call epox_get_product for a URL you can fetch.

Request

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "epox_list_products",
    "arguments": { "search": "lamp", "limit": 20 }
  }
}

Response

json
{
  "items": [
    {
      "id": "prod_9f3a2b",
      "name": "Oakwood Floor Lamp",
      "description": "Warm oak-veneer floor lamp with a linen shade.",
      "sku": "LMP-OAK-014",
      "category": "Lighting",
      "tags": ["lamp", "living-room", "oak"],
      "source": "woocommerce",
      "publishStatus": "published",
      "images": [{ "id": "img_44a1", "isPrimary": true }],
      "updatedAt": "2026-09-18T14:02:11.000Z"
    }
  ],
  "nextCursor": "MjA=",
  "total": 34
}

epox_get_product

Read one workspace product by ID, with a fetchable url for each source photo. The image id is what you pass as primaryId in `epox_start_pack_generation`'s sourceImages.

product is null if no product in your workspace matches id. An image's url is null when its file isn't stored under your workspace.

Request

json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "epox_get_product",
    "arguments": { "id": "prod_9f3a2b" }
  }
}

Response

json
{
  "product": {
    "id": "prod_9f3a2b",
    "name": "Oakwood Floor Lamp",
    "description": "Warm oak-veneer floor lamp with a linen shade.",
    "sku": "LMP-OAK-014",
    "category": "Lighting",
    "tags": ["lamp", "living-room", "oak"],
    "source": "woocommerce",
    "publishStatus": "published",
    "images": [{ "id": "img_44a1", "url": "https://example.com/images/lamp-01.jpg", "isPrimary": true }],
    "updatedAt": "2026-09-18T14:02:11.000Z"
  }
}

Generated assets

epox_list_assets

List generated workspace assets. Filter by productId, flowId (only the assets filed in that flow, to read back a run grouped with `epox_create_session`), status (pending / generating / completed / error), or assetType (image / video / 3d_model), on top of the standard limit/cursor/search.

  • total is the number of assets the filters match across every page, so "how many finished images does this product have" is one call with status: "completed" and assetType: "image" — no paging and adding.
  • hasFile only says whether a file could be downloaded — it is not a link.
  • Call epox_get_asset with includeDownloadUrl: true for the asset you actually need.

Request

json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "epox_list_assets",
    "arguments": { "productId": "prod_9f3a2b", "status": "completed", "limit": 10 }
  }
}

Response

json
{
  "items": [
    {
      "id": "asset_7c21",
      "type": "image",
      "status": "completed",
      "approvalStatus": "approved",
      "productIds": ["prod_9f3a2b"],
      "flowId": "flow_1e90",
      "jobId": "job_5b6a",
      "error": null,
      "hasFile": true,
      "createdAt": "2026-09-18T14:05:02.000Z",
      "completedAt": "2026-09-18T14:06:40.000Z"
    }
  ],
  "nextCursor": null,
  "total": 1
}

epox_search_assets

Search generated assets by linked product or collection text. Same filters (including flowId) and response shape as epox_list_assets, but search is required rather than optional.

Request

json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "epox_search_assets",
    "arguments": { "search": "floor lamp" }
  }
}

Response

json
{
  "items": [
    {
      "id": "asset_7c21",
      "type": "image",
      "status": "completed",
      "approvalStatus": "approved",
      "productIds": ["prod_9f3a2b"],
      "flowId": "flow_1e90",
      "jobId": "job_5b6a",
      "error": null,
      "hasFile": true,
      "createdAt": "2026-09-18T14:05:02.000Z",
      "completedAt": "2026-09-18T14:06:40.000Z"
    }
  ],
  "nextCursor": null,
  "total": 1
}

epox_get_asset

Read one generated workspace asset by ID, including the prompt it was generated from. Pass includeDownloadUrl: true only when you need the file itself — it returns a link that expires after 15 minutes and that anyone holding it can use, so request it only when you are about to fetch the file.

Omit includeDownloadUrl (or pass false) and the response has the same shape without url. asset is null if no asset in your workspace matches id.

Request

json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "epox_get_asset",
    "arguments": { "id": "asset_7c21", "includeDownloadUrl": true }
  }
}

Response

json
{
  "asset": {
    "id": "asset_7c21",
    "type": "image",
    "status": "completed",
    "approvalStatus": "approved",
    "productIds": ["prod_9f3a2b"],
    "flowId": "flow_1e90",
    "jobId": "job_5b6a",
    "prompt": "Studio lifestyle shot of the lamp beside a linen armchair",
    "error": null,
    "hasFile": true,
    "createdAt": "2026-09-18T14:05:02.000Z",
    "completedAt": "2026-09-18T14:06:40.000Z",
    "url": "https://…/asset_7c21.jpg?…"
  }
}

Collections

epox_list_collections

List workspace collections.

Request

json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "epox_list_collections",
    "arguments": { "limit": 20 }
  }
}

Response

json
{
  "items": [
    {
      "id": "coll_2d18",
      "name": "Autumn Living Room Refresh",
      "status": "completed",
      "productIds": ["prod_9f3a2b", "prod_11ffa2"],
      "packId": "pack_lifestyle_01",
      "packRunId": "run_88ac",
      "isPinned": false,
      "updatedAt": "2026-09-20T09:11:00.000Z"
    }
  ],
  "nextCursor": null,
  "total": 1
}

epox_get_collection

Read one workspace collection by ID.

collection is null if no collection in your workspace matches id.

Request

json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "epox_get_collection",
    "arguments": { "id": "coll_2d18" }
  }
}

Response

json
{
  "collection": {
    "id": "coll_2d18",
    "name": "Autumn Living Room Refresh",
    "status": "completed",
    "productIds": ["prod_9f3a2b", "prod_11ffa2"],
    "packId": "pack_lifestyle_01",
    "packRunId": "run_88ac",
    "isPinned": false,
    "updatedAt": "2026-09-20T09:11:00.000Z"
  }
}

Models

epox_list_models

  • List the image and video generation models this workspace can use, with their resolutions, durations, credit prices and capabilities.
  • It needs only mcp:read.
  • A model's id is what you pass as imageModel to epox_generate_image and epox_start_generation, or as model to epox_start_video.
  • Only models your workspace is offered are listed, which is not the same as every model Epox knows.

Arguments

  • `type` (optional) — image or video. Omit it for both.
  • defaults holds the model used when you pass none: the workspace's pinned default if it has one, otherwise Epox's.
  • With type: "video" only video is returned and with type: "image" only image.
  • Each image model carries id, name, description, tier, speed, quality, tags, resolutions ({ resolution, creditsPerImage } for each) and maxReferenceImages.
  • Each video model carries the fields above, with creditsPerClip priced for one clip without audio (models that price audio can cost more with sound on).
  • A price is null when none is configured.
  • maxShots is 0 for a model that isn't multi-shot, and maxReferenceImages is null on an image model when no cap is set.

Request

json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": { "name": "epox_list_models", "arguments": { "type": "video" } }
}

Response

json
{
  "defaults": { "image": "image_model_default", "video": "video_model_default" },
  "video": [
    {
      "id": "video_model_default",
      "name": "Example video model",
      "description": "Short description of the model.",
      "tier": "standard",
      "speed": "medium",
      "quality": "high",
      "tags": ["Multi-shot"],
      "options": [
        { "resolution": "720p", "duration": "5s", "creditsPerClip": 40 },
        { "resolution": "1080p", "duration": "5s", "creditsPerClip": 70 }
      ],
      "supportsEndFrame": true,
      "multiShot": true,
      "maxShots": 6,
      "maxReferenceImages": 4,
      "maxReferenceVideos": 0
    }
  ]
}

epox_recommend_model

  • Rank the models this workspace can use for a goal, so you don't have to read the whole epox_list_models list.
  • It needs only mcp:read.
  • Ranking is plain: it reads each model's quality, speed, price and capabilities from the same data as epox_list_models, and gives a reason for each pick.

Arguments

  • `type` (string, required) — image or video.
  • `needs` (array, optional, up to 6) — capabilities the model must have. Image: text_rendering, reference_images, editing. Video: audio, multi_shot, end_frame, reference_images. A model missing any need is left out.
  • `priority` (optional) — quality (the default), speed or cost.
  • `limit` (optional integer, 1–5) — how many to return. Defaults to 3.
  • recommendations entries are { id, name, reason }; pass id as model to epox_start_video or imageModel to epox_generate_image.
  • excludedForMissingCapabilities counts the models dropped for lacking a need.
  • When nothing qualifies, recommendations is empty and a note suggests dropping a need or calling epox_list_models.
  • The example's reason text is illustrative; read the real one from the response.

Request

json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "epox_recommend_model",
    "arguments": { "type": "video", "needs": ["audio", "end_frame"], "priority": "quality", "limit": 2 }
  }
}

Response

json
{
  "type": "video",
  "recommendations": [
    { "id": "video_model_default", "name": "Example video model", "reason": "Generates sound and accepts an end frame; ultra quality." }
  ],
  "excludedForMissingCapabilities": 3
}

Resources

Resources are fixed, read-only snapshots fetched with resources/read instead of tools/call. Call resources/list to discover them.

  • `epox://workspace/summary` is the workspace's { id, name }.
  • `epox://workspace/products` is up to 50 products, most recently updated first, in the same shape as epox_list_products items. It is not paginated; use epox_list_products to page through more.
json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "resources/read",
  "params": { "uri": "epox://workspace/summary" }
}

The result is { "contents": [{ "uri", "mimeType", "text" }] }, where text is a JSON string holding { notice, data }.

Next steps

Was this guide useful?Your feedback helps us refine the documentation.

Keep going

Related guides

Developer overviewConnecting an MCP clientWorkspace & try-on toolsGeneration & automations tools