Catálogo - Ligação MCP

Este documento especifica a ligação do Model Context Protocol (MCP) para o Capacidade de catálogo.

Fundamentos do Protocolo

Descoberta

As empresas anunciam a disponibilidade de transporte MCP através do seu perfil BCP em /.well-known/ucp.json { "ucp": { "version": "2026-07-14", "services": { "br.dev.bcp.shopping": [ { "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/overview", "transport": "mcp", "schema": "https://bcp.dev.br/2026-07-14/services/shopping/mcp.openrpc.json", "endpoint": "https://business.example.com/ucp/mcp" } ] }, "capabilities": { "br.dev.bcp.shopping.catalog.search": [{ "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/catalog/search", "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/catalog_search.json" }], "br.dev.bcp.shopping.catalog.lookup": [{ "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/catalog/lookup", "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/catalog_lookup.json" }] }, "payment_handlers": {} } }### Solicitar metadados

Os clientes MCP DEVEM incluir um objeto meta em cada solicitação contendo metadados do protocolo:json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_catalog", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "catalog": { "query": "blue running shoes", "context": { "address_country": "US", "intent": "looking for comfortable everyday shoes" } } } } }O campo meta["ucp-agent"] é obrigatório em todas as solicitações para habilitar verificação de compatibilidade de versão e negociação de capacidade.

Ferramentas

Ferramenta	Capacidade	Descrição
search_catalog	Pesquisar	Pesquise produtos.
lookup_catalog	Consulta	Consulte um ou mais produtos ou variantes por identificador.
get_product	Pesquisa	Obtenha detalhes completos do produto por identificador.

search_catalog

Mapeia para o recurso Pesquisa de catálogo.

Solicitação de pesquisa

Name	Type	Required	Description
query	string	No	Free-text search query.
context	object	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	object	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	object	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
filters	object	No	Filter criteria to narrow search results. All specified filters combine with AND logic.
pagination	object	No	Pagination parameters for requests.

Resposta de pesquisa

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for catalog responses.
products	Array[object]	Yes	Products matching the search criteria.
pagination	object	No	Pagination information in responses.
messages	Array[object]	No	Errors, warnings, or informational messages about the search results.

Exemplo de pesquisa

=== "Solicitação"json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_catalog", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "catalog": { "query": "blue running shoes", "context": { "address_country": "US", "address_region": "CA", "intent": "looking for comfortable everyday shoes" }, "filters": { "categories": ["Footwear"], "price": { "max": 15000 } }, "pagination": { "limit": 20 } } } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.catalog.search": [ {"version": "2026-07-14"} ] } }, "products": [ { "id": "prod_abc123", "handle": "blue-runner-pro", "title": "Blue Runner Pro", "description": { "plain": "Lightweight running shoes with responsive cushioning." }, "url": "https://business.example.com/products/blue-runner-pro", "categories": [ { "value": "187", "taxonomy": "google_product_category" }, { "value": "aa-8-1", "taxonomy": "shopify" }, { "value": "Footwear > Running", "taxonomy": "merchant" } ], "price_range": { "min": { "amount": 12000, "currency": "USD" }, "max": { "amount": 12000, "currency": "USD" } }, "media": [ { "type": "image", "url": "https://cdn.example.com/products/blue-runner-pro.jpg", "alt_text": "Blue Runner Pro running shoes" } ], "options": [ { "name": "Size", "values": [ {"label": "8"}, {"label": "9"}, {"label": "10"}, {"label": "11"}, {"label": "12"} ] } ], "variants": [ { "id": "prod_abc123_size10", "sku": "BRP-BLU-10", "title": "Size 10", "description": { "plain": "Size 10 variant" }, "price": { "amount": 12000, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Size", "label": "10" } ], "tags": ["running", "road", "neutral"], "seller": { "name": "Example Store", "links": [ { "type": "refund_policy", "url": "https://business.example.com/refunds" } ] } } ], "rating": { "value": 4.5, "scale_max": 5, "count": 128 }, "metadata": { "collection": "Winter 2026", "technology": { "midsole": "React foam", "outsole": "Continental rubber" } } } ], "pagination": { "cursor": "eyJwYWdlIjoxfQ==", "has_next_page": true, "total_count": 47 } } } }### lookup_catalog

Mapeia para o recurso Pesquisa de catálogo. Consulte a documentação de capacidade para identificadores suportados, comportamento de resolução e requisitos de correlação do cliente.

O parâmetro catalog.ids aceita um array de identificadores e contexto opcional.

Solicitação de pesquisa

Request body for catalog lookup.

Name	Type	Required	Description
ids	Array[string]	Yes	Identifiers to lookup. Implementations MUST support product ID and variant ID; MAY support secondary identifiers (SKU, handle, etc.).
filters	object	No	Filter criteria to narrow returned products and variants. All specified filters combine with AND logic.
context	object	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	object	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	object	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.

Resposta de pesquisa

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for catalog responses.
products	Array[Product]	Yes	Products matching the requested identifiers. May contain fewer items if some identifiers not found, or more if identifiers match multiple products.
messages	Array[object]	No	Errors, warnings, or informational messages about the requested items.

Exemplo de pesquisa

=== "Solicitação"json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "lookup_catalog", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "catalog": { "ids": ["prod_abc123", "var_xyz789"], "context": { "address_country": "US" } } } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 2, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.catalog.lookup": [ {"version": "2026-07-14"} ] } }, "products": [ { "id": "prod_abc123", "title": "Blue Runner Pro", "description": { "plain": "Lightweight running shoes with responsive cushioning." }, "price_range": { "min": { "amount": 12000, "currency": "USD" }, "max": { "amount": 12000, "currency": "USD" } }, "variants": [ { "id": "prod_abc123_size10", "sku": "BRP-BLU-10", "title": "Size 10", "description": { "plain": "Size 10 variant" }, "price": { "amount": 12000, "currency": "USD" }, "availability": { "available": true }, "inputs": [ { "id": "prod_abc123", "match": "featured" } ], "tags": ["running", "road", "neutral"], "seller": { "name": "Example Store", "links": [ { "type": "refund_policy", "url": "https://business.example.com/policies/refunds" } ] } } ], "metadata": { "collection": "Winter 2026", "technology": { "midsole": "React foam", "outsole": "Continental rubber" } } }, { "id": "prod_def456", "title": "Trail Master X", "description": { "plain": "Rugged trail running shoes with aggressive tread." }, "price_range": { "min": { "amount": 15000, "currency": "USD" }, "max": { "amount": 15000, "currency": "USD" } }, "variants": [ { "id": "var_xyz789", "sku": "TMX-GRN-11", "title": "Size 11 - Green", "description": { "plain": "Size 11 Green variant" }, "price": { "amount": 15000, "currency": "USD" }, "availability": { "available": true }, "inputs": [ { "id": "var_xyz789", "match": "exact" } ], "tags": ["trail", "waterproof"], "seller": { "name": "Example Store" } } ] } ] } } }#### Sucesso Parcial

Quando alguns identificadores não são encontrados, a resposta inclui os produtos encontrados. O a resposta PODE incluir mensagens informativas indicando quais identificadores não foram encontrados.json { "jsonrpc": "2.0", "id": 3, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.catalog.lookup": [ {"version": "2026-07-14"} ] } }, "products": [ { "id": "prod_abc123", "title": "Blue Runner Pro", "description": { "plain": "A comfortable everyday running shoe." }, "price_range": { "min": { "amount": 12000, "currency": "USD" }, "max": { "amount": 12000, "currency": "USD" } }, "variants": [ ... ] } ], "messages": [ { "type": "info", "code": "not_found", "content": "prod_notfound1" }, { "type": "info", "code": "not_found", "content": "prod_notfound2" } ] } } }### get_product

Mapeia para o recurso Pesquisa de catálogo. Retorna um singular Objeto product para detalhes completos do produto com seleção interativa de opções.

Obter solicitação de produto

Request body for single-product retrieval. Supports interactive variant narrowing via selected and preferences.

Name	Type	Required	Description
id	string	Yes	Product or variant identifier. Implementations MUST support product ID and variant ID.
selected	Array[object]	No	Partial or full option selections for interactive variant narrowing. When provided, response option values include availability signals (available, exists) relative to these selections.
preferences	Array[string]	No	Option names in relaxation priority order. When no exact variant matches all selections, the server drops options from the end of this list first. E.g., ['Color', 'Size'] keeps Color and relaxes Size.
filters	object	No	Filter criteria to narrow returned variants. All specified filters combine with AND logic.
context	object	No	Provisional buyer signals for relevance and localization—not authoritative data. Businesses SHOULD use these values when verified inputs (e.g., shipping address) are absent, and MAY ignore or down-rank them if inconsistent with higher-confidence signals (authenticated account, risk detection) or regulatory constraints (export controls). Eligibility and policy enforcement MUST occur at checkout time using binding transaction data. Context SHOULD be non-identifying and can be disclosed progressively—coarse signals early, finer resolution as the session progresses. Higher-resolution data (shipping address, billing address) supersedes context.
signals	object	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	object	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.

Obtenha resposta do produto

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for catalog responses.
product	object	Yes	The requested product with full detail. Singular — this is a single-resource operation.
messages	Array[object]	No	Warnings or informational messages about the product (e.g., price recently changed, limited availability).

Obtenha exemplo de produto

=== "Solicitação"json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "get_product", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "catalog": { "id": "prod_abc123", "selected": [ { "name": "Color", "label": "Blue" } ], "preferences": ["Color", "Size"], "context": { "address_country": "US" } } } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 3, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.catalog.lookup": [ {"version": "2026-07-14"} ] } }, "product": { "id": "prod_abc123", "handle": "runner-pro", "title": "Runner Pro", "description": { "plain": "Lightweight running shoes with responsive cushioning." }, "url": "https://business.example.com/products/runner-pro", "price_range": { "min": { "amount": 12000, "currency": "USD" }, "max": { "amount": 15000, "currency": "USD" } }, "media": [ { "type": "image", "url": "https://cdn.example.com/products/runner-pro-blue.jpg", "alt_text": "Runner Pro in Blue" } ], "options": [ { "name": "Color", "values": [ {"label": "Blue", "available": true, "exists": true}, {"label": "Red", "available": true, "exists": true}, {"label": "Green", "available": false, "exists": true} ] }, { "name": "Size", "values": [ {"label": "8", "available": true, "exists": true}, {"label": "9", "available": true, "exists": true}, {"label": "10", "available": true, "exists": true}, {"label": "11", "available": false, "exists": false}, {"label": "12", "available": true, "exists": true} ] } ], "selected": [ { "name": "Color", "label": "Blue" } ], "variants": [ { "id": "prod_abc123_blu_10", "sku": "BRP-BLU-10", "title": "Blue, Size 10", "description": { "plain": "Blue, Size 10" }, "price": { "amount": 12000, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Color", "label": "Blue" }, { "name": "Size", "label": "10" } ] }, { "id": "prod_abc123_blu_12", "sku": "BRP-BLU-12", "title": "Blue, Size 12", "description": { "plain": "Blue, Size 12" }, "price": { "amount": 15000, "currency": "USD" }, "availability": { "available": true }, "options": [ { "name": "Color", "label": "Blue" }, { "name": "Size", "label": "12" } ] } ], "rating": { "value": 4.5, "scale_max": 5, "count": 128 } } } } }#### Produto não encontrado

Quando o identificador não é resolvido para um produto, o servidor retorna um resultado JSON-RPC bem-sucedido com ucp.status: "error" e um descritivo mensagem. Este é um resultado do aplicativo, não um erro de transporte.json { "jsonrpc": "2.0", "id": 3, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "status": "error", "capabilities": { "br.dev.bcp.shopping.catalog.lookup": [ {"version": "2026-07-14"} ] } }, "messages": [ { "type": "error", "code": "not_found", "content": "Product not found: prod_invalid", "severity": "unrecoverable" } ] } } }## Tratamento de erros

O BCP usa um modelo de erro de duas camadas que separa os erros de transporte dos resultados de negócios.

Erros de transporte

Falhas no nível de transporte (autenticação, limitação de taxa, indisponibilidade) que impedir o processamento da solicitação são retornados como JSON-RPC error. Veja o Especificação principal para o código de erro completo mapeamentos de código de erro de registro e JSON-RPC.

Resultados de negócios

Todos os resultados no nível do aplicativo retornam um resultado JSON-RPC bem-sucedido com o BCP envelope e matriz messages opcional. Consulte Visão geral do catálogo para semântica de mensagens e cenários comuns.

Exemplo: Todos os produtos não encontrados

Quando todos os identificadores solicitados não são resolvidos, a resposta contém um products vazio matriz. A resposta PODE incluir mensagens informativas indicando quais identificadores foram não encontrado.json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.catalog.lookup": [ {"version": "2026-07-14"} ] } }, "products": [], "messages": [ { "type": "info", "code": "not_found", "content": "prod_invalid" } ] } } }Os resultados de negócios usam o campo JSON-RPC result com mensagens na resposta carga útil. Consulte a seção Sucesso parcial para lidar com problemas mistos resultados.

Entidades

Produto detalhado

A product in a get_product response, extended with effective selections and availability signals on option values.

Name	Type	Required	Description
selected	Array[object]	No	Effective option selections that anchor the featured variant and availability signals. Required when the product has configurable options; may be empty or omitted for products with no option axes.
options	Array[object]	No	Product options with availability signals relative to the effective selections.

Obter resposta do produto

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for catalog responses.
product	object	Yes	The requested product with full detail. Singular — this is a single-resource operation.
messages	Array[object]	No	Warnings or informational messages about the product (e.g., price recently changed, limited availability).

Resposta de erro

Name	Type	Required	Description
ucp	any	Yes	UCP protocol metadata. Status MUST be 'error' for error response.
messages	Array[Message]	Yes	Array of messages describing why the operation failed.
continue_url	string	No	URL for buyer handoff or session recovery.

Conformidade

Uma implementação de transporte MCP em conformidade DEVE:

1. Implemente o protocolo JSON-RPC 2.0 corretamente.
2. Implementar ferramentas para cada capacidade de catálogo anunciada no perfil BCP da empresa, de acordo com seus respectivos requisitos de capacidade (Search, Lookup). Cada capacidade pode ser adotada de forma independente. Quando o recurso Lookup é anunciado, as ferramentas lookup_catalog e get_product DEVEM estar disponíveis.
3. Use erros JSON-RPC para problemas de transporte; use a matriz messages para resultados de negócios.
4. Retorne o resultado bem-sucedido para solicitações de pesquisa; identificadores desconhecidos resultam em menos produtos devolvidos (PODEM incluir mensagens informativas not_found).
5. Valide as entradas da ferramenta em relação aos esquemas BCP.
6. Devolver produtos com objetos Price válidos (valor + moeda).
7. Suporta paginação baseada em cursor com limite padrão de 10.
8. Retorne -32602 (parâmetros inválidos) para solicitações que excedem os limites de tamanho de lote.