Model Context Protocol (MCP) Data Types

This page details the common data types used across various Model Context Protocol (MCP) tools for representing product information. These structures ensure a consistent and clear contract for API consumers interacting with search and discovery functionalities.

McpItem

The McpItem object represents a single product or product variant in the MCP response. It provides core identity, attributes, and visual information.

id (string): The merchant’s unique product identifier.
entity_type (string): The type of entity represented (e.g., "product", "item_group").
images (array of McpImage): A list of images associated with the item.
attributes (object): A map of product attributes, where keys are attribute names and values are their corresponding data. The specific attributes included depend on the tool and requested columns.
preferred_image (McpImage, nullable): The image considered most relevant for this item, often a lead image from a search result. Absent when no preferred image is available.
siblings (McpSiblings, nullable): Present when this item stands in for a group of variants — the other variants the site groups with this one (for example one shirt offered in several colors and sizes). Everything inside describes those OTHER variants, not this item. Absent when grouping is off, or when no other variant grouped with this one was surfaced.

McpImage

The McpImage object provides details about an item’s image, including its URL and a thumbnail.

url (string): The URL of the full-resolution image.
thumbnail_url (string, nullable): A CDN-hosted preview of the image, suitable for rendering a small thumbnail. Absent when no preview is available.

McpSiblings

The McpSiblings object provides context for items that belong to a product group (variants). It describes the attributes that vary across the group and lists the other relevant members.

The group context carried by one representative variant: the shared item_group_id, the attributes that vary across the group, and the group’s other variants relevant to this result. This is a focused selection scoped to the current request, not the group’s full membership — for every variant that exists, regardless of this request, call get_item_group with the item_group_id.

item_group_id (string): The merchant’s item-group identifier, shared by every variant shown here.
items (array of McpItem): The group’s other variants relevant to this result (this item excluded): the variants that matter here, a focused selection rather than the group’s full membership. For every variant that exists, regardless of this result, call get_item_group with the item_group_id. Each variant carries only its id, its values for the varying attributes, and its images; a variant never carries its own siblings.
options (array of McpVaryingAttribute): The attributes that vary across the group, each with the distinct values it takes (for example color: [red, blue]). This provides a summary of the variation within the group, not a matrix of all possible combinations. This array may be empty if no attributes vary or are recognized as varying.

McpVaryingAttribute

The McpVaryingAttribute object describes a single attribute that varies among members of an item group. This type was previously named McpSiblingOption. Varying attributes are derived from the distinct values observed for a specific attribute across all relevant members of an item group. An attribute is reported if it carries at least two distinct CAP-resolved values across the members, in first-seen order. If there are fewer than two members, or if the attribute is constant across all members, it yields an empty result.

name (string): The name of the varying attribute (e.g., "color", "size").
values (array): A list of the distinct values this attribute takes across the group members. The type of values in this array can vary based on the attribute’s type (e.g., strings for “size”, objects for “color”).

McpMemoryItem

The McpMemoryItem object represents a single item stored in conversation memory.

seq (uint64): Sequence number of the item: per conversation, 0-based, gapless, in append order.
recorded_at (string): Server-side commit time of the item’s batch, as an RFC3339 timestamp; all items appended in one batch share it.
payload (object): The remembered JSON object, exactly as it was appended — contents are stored verbatim, never interpreted.

McpConversationSummary

The McpConversationSummary object provides a summary of a conversation stored in memory, listing its identifier and key timestamps without item contents.

conversation_id (string): The pseudonymous conversation id, exactly as minted by the client.
created_at (string): When the conversation’s first item was recorded, as an RFC3339 timestamp.
last_appended_at (string): When the conversation’s most recent item was recorded, as an RFC3339 timestamp — the field the list is ordered by, most recent first.

McpCropArea

The McpCropArea object defines a region of an image to be used for visual search, instead of the entire image. This is a relative rectangle: x/y locate the upper-left corner as fractions of the image width/height, and width/height give the size as the same fractions. All four are in [0,1], and the region must lie inside the image: width > 0, height > 0, x + width <= 1, y + height <= 1.

x (float): Relative x-coordinate of the upper-left corner.
y (float): Relative y-coordinate of the upper-left corner.
width (float): Relative width of the crop area.
height (float): Relative height of the crop area.

McpBoundingBox

The McpBoundingBox object locates a detected object within an image, using the same relative-rectangle convention as McpCropArea: all four values are fractions of the image’s width or height.

x (float): Relative x-coordinate of the upper-left corner.
y (float): Relative y-coordinate of the upper-left corner.
width (float): Relative width of the box.
height (float): Relative height of the box.

McpDetectedObject

The McpDetectedObject object describes one object that object detection found in an image supplied to visual_search. Its bounding_box can be echoed back as a later request’s crop to search by just that region.

bounding_box (McpBoundingBox): Where the object sits in the image.
confidence (float): How confident detection is that the object is there.
object_class (string, optional): The detected class, when the model assigned one.

McpStaticFilter

The McpStaticFilter object is a recursive boolean filter tree, passed as a search tool’s additional_filter to constrain the candidate set before ranking. Every node carries a kind that determines its remaining fields.

Logical nodes combine other filters:

{ "kind": "and", "filters": [...] }: All child filters must hold.
{ "kind": "or", "filters": [...] }: At least one child filter must hold.
{ "kind": "not", "filter": {...} }: The child filter must not hold.

Comparison nodes test one column, naming it in column and the value to compare against in value:

{ "kind": "equals", "column": ..., "value": ... } and not_equals: Equality and its negation.
{ "kind": "lt" | "lte" | "gt" | "gte", "column": ..., "value": ... }: Ordered comparisons, for numeric columns.

One node matches category trees:

{ "kind": "path_covers", "column": ..., "values": [...] }: Matches products whose category path is covered by the given path segments.

The accepted shape of value depends on the column’s type, so name only columns reported by list_relevant_columns and check their value space with describe_column first.

McpDynamicFilterSelection

The McpDynamicFilterSelection object is one facet selection passed back into a search tool’s dynamic_filters, refining a result set without changing the underlying ranked candidate set.

column (string): The column being refined, taken from a previous response’s dynamic_filters.
values (array): Selection values echoed back from that response’s options. The accepted shape depends on the column type: a string, number, or boolean; ["path", "segments"] for tree paths; or {start?, end?} for interval ranges, with a special case for the color column. In normal usage an agent does not set dynamic_filters on the first request — it reads the shapes off the first response and echoes matching values back on the next call.

McpDynamicFilter

The McpDynamicFilter object is one facet a search response offers for refining its results.

column (string): The column this facet refines.
options (McpFilterOptions): The values or range the facet offers.
title (string, optional): A human-readable label for the facet, when the merchant configured one.

McpFilterOptions

The McpFilterOptions object carries a facet’s available values. Branch on kind:

{ "kind": "categorical", "values": [...] }: The distinct values the facet offers.
{ "kind": "interval", "minimum": ..., "maximum": ..., "histogram": [...] }: A numeric range, with minimum and maximum bounds (either may be absent) and a histogram of McpIntervalBucket distribution buckets. The histogram is empty when none is available.

McpIntervalBucket

The McpIntervalBucket object is one bucket in an interval facet’s distribution histogram.

start (float, optional): Lower bound of the bucket; absent when unbounded.
end (float, optional): Upper bound of the bucket; absent when unbounded.
frequency (float): How much of the result set falls in this bucket.

McpStreamItem

The McpStreamItem object carries a piece of narrative a search produced alongside its results — for example a filter the query implied, a category prediction, or a recognized barcode. Anchor-based recommendation tools never produce stream items.

parts (array of McpStreamPart): The ordered parts making up this item.

McpStreamPart

The McpStreamPart object is one part of an McpStreamItem. Branch on kind:

{ "kind": "text", "text": ... }: A run of text.