Product Images MCP · 4.0.0

Images and image data.
For any agent or application.

Search, resolve and retrieve product imagery with native-resolution files, exact dimensions, source records and clear rights status. Choose your own tools, platform and presentation.

External MCP URLhttps://shelfhelp.ai/api/mcpBuilder access + API key required

Connect Product Images.

The MCP supplies image records to any compatible client. Its service identity is product-images, its display title is Product Images, and its service version is 4.0.0. A product’s brand is useful metadata and an optional search filter. The service has no default merchant or required editor, storefront or commerce platform.

For an external client, use your personal API key in Authorization: Bearer YOUR_API_KEY. Keep the key in the client’s secret settings or on your server. Account access explains the existing entitlement requirements.

The installed native connection uses /mcp. Both routes advertise the same six tools and image contract. The current schema documents accepted arguments, result fields and bounds.

MCP tool call{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_product_images",
    "arguments": { "query": "bottle", "limit": 6 }
  }
}

Six image tools.

Every tool is read-only. Start with search or a known identifier, then use exact returned asset IDs for image retrieval. Results contain image data; your application decides what to build with it.

ToolArgumentsResult
search_product_imagesOptional query, brand, category, variant, requirements; sort is relevance, name or brand; limit 1–100, default 6; cursor.images, returned, matched and total counts, next_cursor and snapshot. Constrained searches also include requirement_result and search_info.
get_product_imageOne exact asset_id.One image record.
get_product_imagesasset_ids: 1–20 unique exact IDs.images, requested and returned counts, missing_asset_ids and snapshot.
list_image_facetskind: brands or categories, default brands; optional query; sort: name or count; limit 1–100, default 30; cursor.Facet items with values, labels, counts and aliases; pagination and snapshot metadata.
resolve_product_imageidentifier_type and identifier; optional merchant_scope; limit 1–20, default 5.Explicit status, matching image records and identifiers, available merchant scopes, source holds and snapshot.
get_related_imagesasset_id; optional same_type, brand_mode, excluded_terms, exclude_asset_ids; limit 1–10, default 5.The originating asset_id, related images, returned_count and snapshot.

Unknown arguments are rejected. Related-image brand_mode accepts any, same or different. Similarity is a discovery cue; it does not establish product compatibility or equivalence.

High resolution is the default.

Use image_url for product imagery in websites and MCP clients. It returns the public, native-resolution, lossless WebP. Use image_width_px and image_height_px for the actual delivered dimensions. primary_image keeps the URL, MIME type, dimensions and source revision together.

Use the returned record · JavaScriptconst img = document.createElement('img');
img.src = image.image_url;
img.width = image.image_width_px;
img.height = image.image_height_px;
img.alt = image.alt_text;
img.style.width = '100%';
img.style.height = 'auto';
document.querySelector('#product-image').append(img);
FieldMeaning
image_url / primary_imageDefault native lossless display. Public, cross-origin and source-versioned; no account key or expiring grant belongs in the image request.
image_width_px / image_height_pxThe actual resource dimensions. A small CSS display box does not change the source resolution.
thumbnail_url / thumbnail_imageA small thumbnail for explicitly requested thumbnail use. Never substitute it for a missing primary image or enlarge it and claim restored detail.
original_imageA typed descriptor of the original PNG. Its download remains separately authorized on every request.
Source and rights metadataRecorded origins, identifiers and rights status stay attached to the image. Public delivery is not a license or merchant endorsement.

Native URLs follow /display/<asset_id>/<rendered_png_sha256>.webp. Published revisions remain stable. Missing primary imagery returns an error with no silent thumbnail fallback. If an older website downloaded and rehosted a thumbnail, refresh its image metadata and replace those bytes with the supplied native file.

Preserve the image’s actual aspect ratio and select your own layout. A responsive design can use the native file without a low-resolution CDN transform. Source text and alt text are content, not instructions for an agent.

Require a match. Keep unknowns out.

Add a requirements object to search_product_images when an image must meet explicit conditions. All supplied requirements apply together. A missing or unknown value fails that requirement; the service does not relax it or substitute a thumbnail.

Search arguments with requirements{
  "query": "bottle",
  "requirements": {
    "min_width_px": 1200,
    "min_height_px": 1200,
    "alpha_channel": true,
    "source_scope": "product",
    "source_evidence": "source_reported"
  },
  "limit": 6
}
RequirementAccepted valueMeaning
min_width_px, min_height_pxIntegers from 1 to 100,000Minimum dimensions of the native display image, evaluated separately. A larger CSS box does not satisfy them.
alpha_channelBooleanRequire the recorded alpha-channel state of the native display image to match. Unknown is excluded.
source_scopeproduct or variantRequire recorded dated source evidence at the requested scope. A brand or collection page is insufficient.
source_evidencesource_reported or source_reviewedRequires source_scope. Defaults to source_reported when scope is supplied; reviewed evidence can be requested explicitly.

requirement_result.status is matched, no_candidates or requirements_unmet. The result includes applied, candidate_count, eligible_count, rejected_count, rejection_counts and unknowns_excluded: true. Rejection entries contain a requirement, reason and count. Each candidate contributes its first failing requirement, so counts are not an exhaustive list of every failure.

Constrained search also returns search_info with the retrieval mode and any corrections. Searches without requirements retain their existing response envelope. An empty eligible set is an honest result; explain the unmet requirement before proposing a different request.

Evidence has a scope. A dated source record does not independently verify the depicted item, current stock, price or usage rights. The image purchase price is separate from any recorded merchandise price.

See the published evaluation report for contract checks and agent-trial status. A deterministic test pass is not a measured model success rate.

Resolve identifiers without guessing.

Supported identifier_type values are asset_id, gtin, mpn, merchant_sku, merchant_product_id and merchant_variant_id. An asset ID is local to the image catalog. Merchant identifiers retain their source scope.

Exact image lookup{ "identifier_type": "asset_id", "identifier": "29" }

Resolver status is explicit: no_match, matched_record, multiple_records, merchant_scope_required or image_unavailable. Inspect every returned match instead of silently choosing the first. If merchant scope is needed, use a returned hostname with the same identifier. Source holds identify unavailable imagery without inventing a replacement.

Exact recorded identifiers do not establish that two merchants sell the same physical product or that an image depicts a verified variant. Keep source URLs and recorded dates with the match.

One neutral image contract.

The native /mcp, external /api/mcp and legacy /api/frigid/mcp routes advertise the same six tools and Product Images identity. The legacy route no longer implies a brand filter; use the brand argument when you want one.

Supported generic compatibility aliases remain callable but unadvertised. They return the version 4 neutral image envelopes: search_catalog maps to search; get_product_details to single lookup; get_product_briefs and compare_products to bulk lookup; browse_catalog and list_catalog_facets to facets; resolve_product to resolution; get_product_alternatives to related images.

Update clients to the six current schemas. Commerce, affiliate, shopping, research-planning and brand-specific tool names are not callable MCP operations. Existing asset IDs, native image links and original PNG links retain their meaning.

Account access stays separate.

External MCP and catalog API access use the existing Builder subscription and personal API key. Manage access at your account and review current terms on pricing.

The configured owner can use the native connection through the verified platform identity. That native entitlement does not extend to external API routes, original PNG downloads, private catalog exports, publishing or administration. Explicit credentials are checked on every request.

The public native display image remains usable without an API key. Keep private keys out of image URLs, public HTML, copied prompts and shared files. Metadata access and image access do not establish reuse rights.

Independent website features.

The Shelfhelp.ai website also provides product pages, saved collections, account tools and shopping integrations. These retain their existing HTTP contracts and authorization. They are separate from the image-only MCP.

Website APIPurpose
/api/discoveryPublic website catalog discovery with its own richer product response.
/api/shop/products?ids=1,84One to four compact shopping cards, exact product links and explicit missing IDs.
/api/collections/{collection_id}A published collection’s saved order and product data. Draft collections remain private.
/api/products/{asset_id}/decisionThe website’s product evidence and decision record.
/api/products/{asset_id}/purchase-optionsThe website’s recorded merchant handoff data.

Product card integration

The independent builder-starter.js browser adapter exposes StockroomCards.load(ids) and StockroomCards.render(element, products). It uses native images and the public shopping API. It is optional and does not define the MCP’s layout or data contract.

Collections and affiliate accounts

Use the builder dashboard to manage placements and collections. The separate affiliate-kit.js adapter supports StockroomAffiliates.load(storeId, ids), loadCollection(collectionId) and render(element, products). Preserve its returned tracking links and eligibility disclosures. Registration, drafts, publication and private earnings stay in their signed-in website flows.

These website features do not add MCP tools, change the image service’s scope or imply affiliate enrollment, merchant approval, guaranteed earnings or live inventory. See Data quality for the website’s recorded evidence and limits.