Pular para conteúdo

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/bcp.

{
  "ucp": {
    "version": "2026-07-28",
    "services": {
      "br.dev.bcp.shopping": [
        {
          "version": "2026-07-28",
          "spec": "https://bcp.dev.br/draft/specification/overview",
          "transport": "mcp",
          "schema": "https://bcp.dev.br/draft/services/shopping/mcp.openrpc.json",
          "endpoint": "https://business.example.com/bcp/mcp"
        }
      ]
    },
    "capabilities": {
      "br.dev.bcp.shopping.catalog.search": [{
        "version": "2026-07-28",
        "spec": "https://bcp.dev.br/draft/specification/catalog/search",
        "schema": "https://bcp.dev.br/draft/schemas/shopping/catalog_search.json"
      }],
      "br.dev.bcp.shopping.catalog.lookup": [{
        "version": "2026-07-28",
        "spec": "https://bcp.dev.br/draft/specification/catalog/lookup",
        "schema": "https://bcp.dev.br/draft/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:

{
  "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": "BR",
          "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 Consulta Obtenha detalhes completos do produto por identificador.

search_catalog

Mapeia para o recurso Pesquisa de catálogo.

Solicitação de pesquisa

Nome Tipo Obrigatório Descrição
query string Não Consulta de busca em texto livre.
context object Não Sinais provisórios do buyer para relevância e localização—não são dados autoritativos. Empresas DEVERIAM usar estes valores quando entradas verificadas (ex.: endereço de shipping) estiverem ausentes, e PODEM ignorá-los ou reduzir sua prioridade se inconsistentes com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (controles de exportação). A elegibilidade e a aplicação de políticas DEVEM ocorrer no momento do checkout usando dados vinculantes da transação. O Context DEVERIA ser não identificável e pode ser divulgado progressivamente—sinais grosseiros no início, resolução mais fina à medida que a sessão avança. Dados de maior resolução (endereço de shipping, endereço de cobrança) têm precedência sobre o context.
signals object Não Dados de ambiente fornecidos pela plataforma para apoiar a autorização e a prevenção de abusos. Os valores NÃO DEVEM ser declarações afirmadas pelo comprador — as plataformas fornecem sinais com base em observação direta ou em atestações de terceiros verificáveis de forma independente. Todas as chaves de sinal DEVEM usar nomenclatura em domínio reverso para garantir a proveniência e prevenir colisões quando múltiplas extensões contribuem para o namespace compartilhado.
attribution object Não Contexto de indicação e evento de conversão emitido pela plataforma — identificadores de campanha, IDs de clique, marcadores de source/medium, etc. Os mesmos parâmetros que as plataformas comunicam via parâmetros de consulta de URL em fluxos baseados em navegador.
filters object Não Critérios de filtro para restringir os resultados de busca. Todos os filtros especificados se combinam com lógica AND.
pagination object Não Parâmetros de paginação para requisições.

Resposta de pesquisa

Nome Tipo Obrigatório Descrição
ucp any Sim Metadados BCP para respostas de catálogo.
products Array[object] Sim Produtos que correspondem aos critérios de busca.
pagination object Não Informações de paginação nas respostas.
messages Array[object] Não Erros, avisos ou mensagens informativas sobre os resultados da busca.

Exemplo de pesquisa

{
  "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": "BR",
          "address_region": "SP",
          "intent": "looking for comfortable everyday shoes"
        },
        "filters": {
          "categories": ["Footwear"],
          "price": {
            "max": 15000
          }
        },
        "pagination": {
          "limit": 20
        }
      }
    }
  }
}


{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.catalog.search": [
            {"version": "2026-07-28"}
          ]
        }
      },
      "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": "BRL" },
            "max": { "amount": 12000, "currency": "BRL" }
          },
          "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": "BRL" },
              "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 Consulta 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

Corpo da requisição para consulta de catálogo.

Nome Tipo Obrigatório Descrição
ids Array[string] Sim Identificadores a consultar. As implementações DEVEM suportar product ID e variant ID; PODEM suportar identificadores secundários (SKU, handle, etc.).
filters object Não Critérios de filtro para restringir os produtos e variantes retornados. Todos os filtros especificados se combinam com lógica AND.
context object Não Sinais provisórios do buyer para relevância e localização—não são dados autoritativos. Empresas DEVERIAM usar estes valores quando entradas verificadas (ex.: endereço de shipping) estiverem ausentes, e PODEM ignorá-los ou reduzir sua prioridade se inconsistentes com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (controles de exportação). A elegibilidade e a aplicação de políticas DEVEM ocorrer no momento do checkout usando dados vinculantes da transação. O Context DEVERIA ser não identificável e pode ser divulgado progressivamente—sinais grosseiros no início, resolução mais fina à medida que a sessão avança. Dados de maior resolução (endereço de shipping, endereço de cobrança) têm precedência sobre o context.
signals object Não Dados de ambiente fornecidos pela plataforma para apoiar a autorização e a prevenção de abusos. Os valores NÃO DEVEM ser declarações afirmadas pelo comprador — as plataformas fornecem sinais com base em observação direta ou em atestações de terceiros verificáveis de forma independente. Todas as chaves de sinal DEVEM usar nomenclatura em domínio reverso para garantir a proveniência e prevenir colisões quando múltiplas extensões contribuem para o namespace compartilhado.
attribution object Não Contexto de indicação e evento de conversão emitido pela plataforma — identificadores de campanha, IDs de clique, marcadores de source/medium, etc. Os mesmos parâmetros que as plataformas comunicam via parâmetros de consulta de URL em fluxos baseados em navegador.

Resposta de pesquisa

Nome Tipo Obrigatório Descrição
ucp any Sim Metadados BCP para respostas de catálogo.
products Array[Product] Sim Produtos que correspondem aos identificadores solicitados. Pode conter menos itens se alguns identificadores não forem encontrados, ou mais se os identificadores corresponderem a múltiplos produtos.
messages Array[object] Não Erros, avisos ou mensagens informativas sobre os itens solicitados.

Exemplo de pesquisa

{
  "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": "BR"
        }
      }
    }
  }
}


{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.catalog.lookup": [
            {"version": "2026-07-28"}
          ]
        }
      },
      "products": [
        {
          "id": "prod_abc123",
          "title": "Blue Runner Pro",
          "description": {
            "plain": "Lightweight running shoes with responsive cushioning."
          },
          "price_range": {
            "min": { "amount": 12000, "currency": "BRL" },
            "max": { "amount": 12000, "currency": "BRL" }
          },
          "variants": [
            {
              "id": "prod_abc123_size10",
              "sku": "BRP-BLU-10",
              "title": "Size 10",
              "description": { "plain": "Size 10 variant" },
              "price": { "amount": 12000, "currency": "BRL" },
              "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": "BRL" },
            "max": { "amount": 15000, "currency": "BRL" }
          },
          "variants": [
            {
              "id": "var_xyz789",
              "sku": "TMX-GRN-11",
              "title": "Size 11 - Green",
              "description": { "plain": "Size 11 Green variant" },
              "price": { "amount": 15000, "currency": "BRL" },
              "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.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.catalog.lookup": [
            {"version": "2026-07-28"}
          ]
        }
      },
      "products": [
        {
          "id": "prod_abc123",
          "title": "Blue Runner Pro",
          "description": {
            "plain": "A comfortable everyday running shoe."
          },
          "price_range": {
            "min": { "amount": 12000, "currency": "BRL" },
            "max": { "amount": 12000, "currency": "BRL" }
          },
          "variants": [ ... ]
        }
      ],
      "messages": [
        {
          "type": "info",
          "code": "not_found",
          "content": "prod_notfound1"
        },
        {
          "type": "info",
          "code": "not_found",
          "content": "prod_notfound2"
        }
      ]
    }
  }
}

get_product

Mapeia para o recurso Consulta 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

Corpo da requisição para recuperação de produto único. Suporta o refinamento interativo de variantes por meio de selected e preferences.

Nome Tipo Obrigatório Descrição
id string Sim Identificador de produto ou variante. As implementações DEVEM suportar product ID e variant ID.
selected Array[object] Não Seleções de opções parciais ou completas para o refinamento interativo de variantes. Quando fornecidas, os valores de opção na resposta incluem sinais de disponibilidade (available, exists) relativos a essas seleções.
preferences Array[string] Não Nomes de opções em ordem de prioridade de relaxamento. Quando nenhuma variante exata corresponde a todas as seleções, o servidor descarta opções a partir do fim desta lista primeiro. Ex.: ['Color', 'Size'] mantém Color e relaxa Size.
filters object Não Critérios de filtro para restringir as variantes retornadas. Todos os filtros especificados se combinam com lógica AND.
context object Não Sinais provisórios do buyer para relevância e localização—não são dados autoritativos. Empresas DEVERIAM usar estes valores quando entradas verificadas (ex.: endereço de shipping) estiverem ausentes, e PODEM ignorá-los ou reduzir sua prioridade se inconsistentes com sinais de maior confiança (conta autenticada, detecção de risco) ou restrições regulatórias (controles de exportação). A elegibilidade e a aplicação de políticas DEVEM ocorrer no momento do checkout usando dados vinculantes da transação. O Context DEVERIA ser não identificável e pode ser divulgado progressivamente—sinais grosseiros no início, resolução mais fina à medida que a sessão avança. Dados de maior resolução (endereço de shipping, endereço de cobrança) têm precedência sobre o context.
signals object Não Dados de ambiente fornecidos pela plataforma para apoiar a autorização e a prevenção de abusos. Os valores NÃO DEVEM ser declarações afirmadas pelo comprador — as plataformas fornecem sinais com base em observação direta ou em atestações de terceiros verificáveis de forma independente. Todas as chaves de sinal DEVEM usar nomenclatura em domínio reverso para garantir a proveniência e prevenir colisões quando múltiplas extensões contribuem para o namespace compartilhado.
attribution object Não Contexto de indicação e evento de conversão emitido pela plataforma — identificadores de campanha, IDs de clique, marcadores de source/medium, etc. Os mesmos parâmetros que as plataformas comunicam via parâmetros de consulta de URL em fluxos baseados em navegador.

Obtenha resposta do produto

Nome Tipo Obrigatório Descrição
ucp any Sim Metadados BCP para respostas de catálogo.
product object Sim O produto solicitado com detalhe completo. Singular — esta é uma operação de recurso único.
messages Array[object] Não Avisos ou mensagens informativas sobre o produto (ex.: preço alterado recentemente, disponibilidade limitada).

Obtenha exemplo de produto

{
  "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": "BR"
        }
      }
    }
  }
}


{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.catalog.lookup": [
            {"version": "2026-07-28"}
          ]
        }
      },
      "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": "BRL" },
          "max": { "amount": 15000, "currency": "BRL" }
        },
        "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": "BRL" },
            "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": "BRL" },
            "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.

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "status": "error",
        "capabilities": {
          "br.dev.bcp.shopping.catalog.lookup": [
            {"version": "2026-07-28"}
          ]
        }
      },
      "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.

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.catalog.lookup": [
            {"version": "2026-07-28"}
          ]
        }
      },
      "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

Um produto em uma resposta de get_product, estendido com seleções efetivas e sinais de disponibilidade nos valores de opção.

Nome Tipo Obrigatório Descrição
selected Array[object] Não Seleções de opção efetivas que ancoram a variante em destaque e os sinais de disponibilidade. Obrigatórias quando o produto tem opções configuráveis; podem estar vazias ou omitidas para produtos sem eixos de opção.
options Array[object] Não Opções de produto com sinais de disponibilidade relativos às seleções efetivas.

Obter resposta do produto

Nome Tipo Obrigatório Descrição
ucp any Sim Metadados BCP para respostas de catálogo.
product object Sim O produto solicitado com detalhe completo. Singular — esta é uma operação de recurso único.
messages Array[object] Não Avisos ou mensagens informativas sobre o produto (ex.: preço alterado recentemente, disponibilidade limitada).

Resposta de erro

Nome Tipo Obrigatório Descrição
ucp any Sim Metadados do protocolo BCP. O status DEVE ser 'error' para uma resposta de erro.
messages Array[Message] Sim Array de mensagens descrevendo por que a operação falhou.
continue_url string Não URL para handoff do buyer ou recuperação da sessão.

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.