Pular para conteúdo

Capacidade do carrinho - vinculação MCP

Este documento especifica a ligação do Model Context Protocol (MCP) para o Capacidade do carrinho.

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.checkout": [ { "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/checkout", "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/checkout.json" } ], "br.dev.bcp.shopping.cart": [ { "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/cart", "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/cart.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": "create_cart", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" } }, "cart": { "line_items": [ ... ] } } } }O campo meta["ucp-agent"] é obrigatório em todas as solicitações para habilitar negociação de capacidade. Plataformas MAIO incluir campos de metadados adicionais.

Ferramentas

Os recursos do BCP são mapeados 1:1 para as ferramentas do MCP.

Padrão de identificador

As ferramentas MCP separam a identificação de recursos dos dados de carga útil:

  • Solicitações: Para operações em carrinhos existentes (get, update, cancel), um parâmetro id de nível superior identifica o recurso de destino. O cart objeto na carga útil da solicitação NÃO DEVE conter um campo id.
  • Respostas: Todas as respostas incluem cart.id como parte do estado completo do recurso.
  • Criar: A operação create_cart não requer um id no solicitação, e a resposta inclui o cart.id recentemente atribuído.
Ferramenta Operação Descrição
create_cart Criar carrinho Crie uma sessão de carrinho.
get_cart Obter carrinho Faça uma sessão de carrinho.
update_cart Atualizar carrinho Atualize uma sessão de carrinho.
cancel_cart Cancelar carrinho Cancele uma sessão de carrinho.

create_cart

Mapeia para a operação Criar carrinho.

Esquema de entrada

Name Type Required Description
line_items Array[Line Item] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals Signals 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 Attribution 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.
buyer Buyer No Optional buyer information for personalized estimates.

Esquema de saída

Name Type Required Description
ucp any Yes UCP metadata for cart responses. No payment handlers needed pre-checkout.
id string Yes Unique cart identifier.
line_items Array[Line Item Response] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals Signals 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 Attribution 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.
buyer Buyer No Optional buyer information for personalized estimates.
currency string Yes ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals Totals Yes Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages Array[Message] No Validation messages, warnings, or informational notices.
links Array[Link] No Optional merchant links (policies, FAQs).
continue_url string No URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at string No Cart expiry timestamp (RFC 3339). Optional.

Exemplo

=== "Solicitação"json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_cart", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "cart": { "line_items": [ { "item": { "id": "item_123" }, "quantity": 2 } ], "context": { "address_country": "US", "address_region": "CA", "postal_code": "94105" } } } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.checkout": [{"version": "2026-07-14"}], "br.dev.bcp.shopping.cart": [{"version": "2026-07-14"}] } }, "id": "cart_abc123", "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Red T-Shirt", "price": 2500 }, "quantity": 2, "totals": [ {"type": "subtotal", "amount": 5000}, {"type": "total", "amount": 5000} ] } ], "currency": "USD", "totals": [ { "type": "subtotal", "amount": 5000 }, { "type": "total", "amount": 5000 } ], "continue_url": "https://business.example.com/checkout?cart=cart_abc123", "expires_at": "2026-01-16T12:00:00Z" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }=== "Resposta de erro"

Todos os itens fora de estoque — nenhum recurso de carrinho é criado:<!-- ucp:example schema=common/types/error_response op=read direction=response extract=$.result.structuredContent -->```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": { "version": "2026-07-14", "status": "error" },
      "messages": [
        {
          "type": "error",
          "code": "out_of_stock",
          "content": "All requested items are currently out of stock",
          "severity": "unrecoverable"
        }
      ],
      "continue_url": "https://merchant.com/"
    },
    "content": [
      {"type": "text", "text": "{\"ucp\":{…},…}"}
    ]
  }
}
```### `get_cart`

Mapeia para a operação Get Cart.

Esquema de entrada

  • id (String, obrigatório): O ID da sessão do carrinho.

Esquema de saída

Name Type Required Description
ucp any Yes UCP metadata for cart responses. No payment handlers needed pre-checkout.
id string Yes Unique cart identifier.
line_items Array[Line Item Response] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals Signals 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 Attribution 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.
buyer Buyer No Optional buyer information for personalized estimates.
currency string Yes ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals Totals Yes Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages Array[Message] No Validation messages, warnings, or informational notices.
links Array[Link] No Optional merchant links (policies, FAQs).
continue_url string No URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at string No Cart expiry timestamp (RFC 3339). Optional.

Exemplo

=== "Solicitação"json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_cart", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "id": "cart_abc123" } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.checkout": [{"version": "2026-07-14"}], "br.dev.bcp.shopping.cart": [{"version": "2026-07-14"}] } }, "id": "cart_abc123", "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Red T-Shirt", "price": 2500 }, "quantity": 2, "totals": [ {"type": "subtotal", "amount": 5000}, {"type": "total", "amount": 5000} ] } ], "currency": "USD", "totals": [ { "type": "subtotal", "amount": 5000 }, { "type": "total", "amount": 5000 } ], "continue_url": "https://business.example.com/checkout?cart=cart_abc123", "expires_at": "2026-01-16T12:00:00Z" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }=== "Não encontrado"json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "status": "error", "capabilities": { "br.dev.bcp.shopping.cart": [{"version": "2026-07-14"}] } }, "messages": [ { "type": "error", "code": "not_found", "content": "Cart not found or has expired", "severity": "unrecoverable" } ], "continue_url": "https://merchant.com/" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }### update_cart

Mapeia para a operação Atualizar carrinho.

Esquema de entrada

  • id (String, obrigatório): O ID da sessão do carrinho a ser atualizada.
Name Type Required Description
id string Yes Unique cart identifier.
line_items Array[Line Item] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals Signals 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 Attribution 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.
buyer Buyer No Optional buyer information for personalized estimates.

Esquema de saída

Name Type Required Description
ucp any Yes UCP metadata for cart responses. No payment handlers needed pre-checkout.
id string Yes Unique cart identifier.
line_items Array[Line Item Response] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals Signals 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 Attribution 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.
buyer Buyer No Optional buyer information for personalized estimates.
currency string Yes ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals Totals Yes Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages Array[Message] No Validation messages, warnings, or informational notices.
links Array[Link] No Optional merchant links (policies, FAQs).
continue_url string No URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at string No Cart expiry timestamp (RFC 3339). Optional.

Exemplo

=== "Solicitação"json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "update_cart", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "id": "cart_abc123", "cart": { "line_items": [ { "item": { "id": "item_123" }, "quantity": 3 }, { "item": { "id": "item_456" }, "quantity": 1 } ], "context": { "address_country": "US", "address_region": "CA", "postal_code": "94105" } } } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 2, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.checkout": [{"version": "2026-07-14"}], "br.dev.bcp.shopping.cart": [{"version": "2026-07-14"}] } }, "id": "cart_abc123", "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Red T-Shirt", "price": 2500 }, "quantity": 3, "totals": [ {"type": "subtotal", "amount": 7500}, {"type": "total", "amount": 7500} ] }, { "id": "li_2", "item": { "id": "item_456", "title": "Blue Jeans", "price": 7500 }, "quantity": 1, "totals": [ {"type": "subtotal", "amount": 7500}, {"type": "total", "amount": 7500} ] } ], "currency": "USD", "totals": [ { "type": "subtotal", "amount": 15000 }, { "type": "total", "amount": 15000 } ], "continue_url": "https://business.example.com/checkout?cart=cart_abc123", "expires_at": "2026-01-16T12:00:00Z" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }### cancel_cart

Mapeia para a operação Cancelar carrinho.

Esquema de entrada

  • id (String, obrigatório): O ID da sessão do carrinho.

Esquema de saída

Name Type Required Description
ucp any Yes UCP metadata for cart responses. No payment handlers needed pre-checkout.
id string Yes Unique cart identifier.
line_items Array[Line Item Response] Yes Cart line items. Same structure as checkout. Full replacement on update.
context Context No Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals Signals 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 Attribution 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.
buyer Buyer No Optional buyer information for personalized estimates.
currency string Yes ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals Totals Yes Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages Array[Message] No Validation messages, warnings, or informational notices.
links Array[Link] No Optional merchant links (policies, FAQs).
continue_url string No URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at string No Cart expiry timestamp (RFC 3339). Optional.

Exemplo

=== "Solicitação"json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "cancel_cart", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" }, "idempotency-key": "660e8400-e29b-41d4-a716-446655440001" }, "id": "cart_abc123" } } }=== "Resposta"json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "capabilities": { "br.dev.bcp.shopping.checkout": [{"version": "2026-07-14"}], "br.dev.bcp.shopping.cart": [{"version": "2026-07-14"}] } }, "id": "cart_abc123", "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Red T-Shirt", "price": 2500 }, "quantity": 2, "totals": [ {"type": "subtotal", "amount": 5000}, {"type": "total", "amount": 5000} ] } ], "currency": "USD", "totals": [ { "type": "subtotal", "amount": 5000 }, { "type": "total", "amount": 5000 } ], "continue_url": "https://business.example.com/checkout?cart=cart_abc123" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }## Tratamento de erros

O BCP distingue entre erros de protocolo e resultados de negócios. Veja o Especificação principal para o código de erro completo exemplos de vinculação de registro e transporte.

  • Erros de protocolo: falhas no nível de transporte (autenticação, limitação de taxa, indisponibilidade) que impedem o processamento da solicitação. Retornado como JSON-RPC error com código -32000 (ou -32001 para erros de descoberta).
  • Resultados de negócios: resultados em nível de aplicativo de solicitação bem-sucedida processamento, retornado como JSON-RPC result com envelope BCP e messages.

Resultados de negócios

Os resultados de negócios (incluindo erros não encontrados e de validação) são retornados como JSON-RPC result com structuredContent contendo o envelope BCP e messages:json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-07-14", "status": "error", "capabilities": { "br.dev.bcp.shopping.cart": [{"version": "2026-07-14"}] } }, "messages": [ { "type": "error", "code": "not_found", "content": "Cart not found or has expired", "severity": "unrecoverable" } ], "continue_url": "https://merchant.com/" }, "content": [ {"type": "text", "text": "{\"ucp\":{…},…}"} ] } }## Conformidade

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

  1. Implemente o protocolo JSON-RPC 2.0 corretamente.
  2. Forneça todas as ferramentas básicas do carrinho definidas nesta especificação.
  3. Retorne erros de acordo com a especificação principal.
  4. Retorne os resultados de negócios como JSON-RPC result com envelope BCP e Matriz messages.
  5. Valide as entradas da ferramenta em relação aos esquemas BCP.
  6. Suporta transporte HTTP com streaming.