Public Columns in MCP

The Model Context Protocol (MCP) provides a programmatic interface for agents to interact with the vviinn platform. To ensure consistent data exposure and security, all product information surfaced through MCP tools is filtered by a set of “public columns.” These columns define the baseline of what is visible to any API consumer holding a public read-only token, regardless of specific campaign configurations.

What are Public Columns?

Public columns are product fields that are considered safe to expose to external consumers. They are shopper-facing attributes that do not contain sensitive internal data or technical details. This set includes standard e-commerce attributes like title, brand, and price, along with any other fields deemed appropriate for public consumption.

Why Public Columns are Needed

Public columns serve several critical purposes:

• Consistency: They ensure that core product data is consistently exposed, preventing scenarios where a field might be visible for one search request but hidden for another due to differing campaign configurations.
• Security: By explicitly defining a public boundary, the system prevents accidental exposure of internal or sensitive data that might be present in the product catalog but not intended for external consumption.
• Baseline Visibility: They establish a guaranteed set of shopper-facing attributes that agents can always rely on, forming a stable contract for data access.

How Public Columns are Determined

The complete set of public columns for a site is derived through a multi-step process:

1. PUBLIC_DISPLAY_COLUMNS: This is a hardcoded list of foundational shopper-facing attributes. It includes fields that are already public through other platform APIs (e.g., link, description, price) and other standard e-commerce display attributes (e.g., gtin, color, material). These columns are always considered public if they exist in the site’s product schema.
2. Campaign-Derived Relevant Columns: The system also considers columns enabled as dynamic filters across all active search campaign types (Text Search, Visual Search, Similar Products, Cross-Selling). If a merchant has configured a column as a filterable facet (e.g., season, size), that column is also considered public, as it is intended for user interaction.
3. Schema Intersection: Both the PUBLIC_DISPLAY_COLUMNS and the campaign-derived relevant columns are filtered to ensure that only columns actually present in the site’s product schema are included.
4. Union: The final public column set is the union of these two lists. This approach ensures that any column deemed filterable by a campaign is also viewable, upholding the principle that an agent should not be able to filter on a column it cannot see.

Impact on MCP Tools

The public column mechanism directly influences how MCP tools behave:

• columns Parameter Restriction: When an MCP tool accepts a columns parameter (e.g., get_item, get_items, search tools), any requested column must be part of the resolved public set. Columns requested that are not public are silently ignored and not returned. This prevents agents from attempting to retrieve non-public data.
• attributes Output: The attributes object within an McpItem (the standard product representation in MCP responses) will only contain public columns. Internal or sensitive columns, even if present in the raw product data, are filtered out before being sent to the agent.
• Structural Fields: Fields like id and entity_type are considered structural to an McpItem. They are always surfaced at the top level of the McpItem object and are not duplicated within the attributes map. These fields are inherently part of the public contract.

Relationship to DEFAULT_COLUMNS

It is important to distinguish public columns from DEFAULT_COLUMNS:

• DEFAULT_COLUMNS is a curated list of commonly desired attributes that search tools (like Text Search) use when the caller does not specify the columns parameter. It serves as a default projection for convenience.
• The public column set, as described above, is a security boundary. The actual columns returned in any default projection will always be a subset of the public columns, as the public set defines the maximum allowable visibility.