Capacidade de checkout - vinculação MCP¶

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

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.fulfillment": [ { "version": "2026-07-14", "spec": "https://bcp.dev.br/2026-07-14/specification/fulfillment", "schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/fulfillment.json", "extends": "br.dev.bcp.shopping.checkout" } ] }, "payment_handlers": { "com.example.vendor.delegate_payment": [ { "id": "handler_1", "version": "2026-07-14", "spec": "https://example.vendor.com/specs/delegate-payment", "schema": "https://example.vendor.com/schemas/delegate-payment-config.json", "available_instruments": [ {"type": "card", "constraints": {"brands": ["visa", "mastercard"]}} ], "config": {} } ] } } }### 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_checkout", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/shopping-agent.json" }, "idempotency-key": "550e8400-e29b-41d4-a716-446655440000" }, "checkout": { "line_items": [ ... ] } } } }O campo meta["ucp-agent"] é obrigatório em todas as solicitações para habilitar negociação de capacidade. O As operações complete_checkout e cancel_checkout também requerem meta["idempotency-key"] para segurança de nova tentativa. Plataformas PODEM 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:

Pedidos: Para operações em checkouts existentes (get, update, complete, cancel), um parâmetro id de nível superior identifica o alvo recurso. O objeto checkout na carga útil da solicitação NÃO DEVE conter um campo id.
Respostas: Todas as respostas incluem checkout.id como parte do estado completo do recurso.
Criar: A operação create_checkout não requer um id na solicitação e a resposta inclui o checkout.id recentemente atribuído.

Ferramenta	Operação	Descrição
`create_checkout`	Criar Check-out	Crie uma sessão de checkout.
`get_checkout`	Obter check-out	Obtenha uma sessão de checkout.
`update_checkout`	Atualizar Check-out	Atualize uma sessão de checkout.
`complete_checkout`	Check-out completo	Faça o pedido.
`cancel_checkout`	Cancelar check-out	Cancele uma sessão de checkout.

`create_checkout`¶

Mapeia para a operação Criar Checkout.

Esquema de entrada¶

checkout (Checkout): Obrigatório. Contém os dados da sessão de checkout inicial e extensões opcionais.
- Extensões (opcional):
  - br.dev.bcp.shopping.buyer_consent: Consentimento do comprador
  - br.dev.bcp.shopping.fulfillment: Fulfillment
  - br.dev.bcp.shopping.discount: Desconto
  - br.dev.bcp.shopping.ap2_mandate: Mandatos AP2

Esquema de saída¶

Objeto Checkout.

Exemplo¶

=== "Solicitação"json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "create_checkout", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "checkout": { "buyer": { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe" }, "line_items": [ { "id": "li_1", "item": { "id": "item_123" }, "quantity": 1 } ], "currency": "USD", "fulfillment": { "methods": [ { "type": "shipping", "destinations": [ { "street_address": "123 Main St", "address_locality": "Springfield", "address_region": "IL", "postal_code": "62701", "address_country": "US" } ] } ] } } } } }=== "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.fulfillment": [ {"version": "2026-07-14"} ] }, "payment_handlers": { "com.example.vendor.delegate_payment": [ {"id": "handler_1", "version": "2026-07-14", "available_instruments": [{"type": "card"}], "config": {}} ] } }, "id": "checkout_abc123", "status": "incomplete", "buyer": { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe" }, "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Blue Jeans", "price": 5000 }, "quantity": 1, "totals": [ {"type": "subtotal", "amount": 5000}, {"type": "total", "amount": 5000} ] } ], "currency": "USD", "totals": [ { "type": "subtotal", "amount": 5000 }, { "type": "fulfillment", "display_text": "Shipping", "amount": 500 }, { "type": "total", "amount": 5500 } ], "fulfillment": { "methods": [ { "id": "shipping_1", "type": "shipping", "line_item_ids": ["li_1"], "selected_destination_id": "dest_home", "destinations": [ { "id": "dest_home", "street_address": "123 Main St", "address_locality": "Springfield", "address_region": "IL", "postal_code": "62701", "address_country": "US" } ], "groups": [ { "id": "package_1", "line_item_ids": ["li_1"], "selected_option_id": "standard", "options": [ { "id": "standard", "title": "Standard Shipping", "description": "Arrives in 5-7 business days", "totals": [ { "type": "total", "amount": 500 } ] }, { "id": "express", "title": "Express Shipping", "description": "Arrives in 2-3 business days", "totals": [ { "type": "total", "amount": 1000 } ] } ] } ] } ] }, "links": [ { "type": "privacy_policy", "url": "https://business.example.com/privacy" }, { "type": "terms_of_service", "url": "https://business.example.com/terms" } ], "continue_url": "https://business.example.com/checkout-sessions/checkout_abc123", "expires_at": "2026-01-11T18:30:00Z" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }=== "Resposta de erro"

Todos os itens fora de estoque — nenhum recurso de checkout é 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-01-11", "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_checkout`

Mapeia para a operação Get Checkout.

Esquema de entrada¶

id (String): Obrigatório. O ID da sessão de checkout.

Esquema de saída¶

Objeto Checkout.

`update_checkout`¶

Mapeia para a operação Update Checkout.

Esquema de entrada¶

id (String): Obrigatório. O ID da sessão de checkout a ser atualizada.
checkout (Checkout): Obrigatório. Contém os dados atualizados da sessão de checkout.
- Extensões (opcional):
  - br.dev.bcp.shopping.buyer_consent: Consentimento do comprador
  - br.dev.bcp.shopping.fulfillment: Fulfillment
  - br.dev.bcp.shopping.discount: Desconto
  - br.dev.bcp.shopping.ap2_mandate: Mandatos AP2

Esquema de saída¶

Objeto Checkout.

Exemplo¶

=== "Solicitação"json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "update_checkout", "arguments": { "meta": { "ucp-agent": { "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json" } }, "id": "checkout_abc123", "checkout": { "buyer": { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe" }, "line_items": [ { "item": { "id": "item_123" }, "id": "li_1", "quantity": 1 } ], "currency": "USD", "fulfillment": { "methods": [ { "id": "shipping_1", "line_item_ids": ["li_1"], "groups": [ { "id": "package_1", "selected_option_id": "express" } ] } ] } } } } }=== "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.fulfillment": [ {"version": "2026-07-14"} ] }, "payment_handlers": { "com.example.vendor.delegate_payment": [ {"id": "handler_1", "version": "2026-07-14", "available_instruments": [{"type": "card"}], "config": {}} ] } }, "id": "checkout_abc123", "status": "incomplete", "buyer": { "email": "jane.doe@example.com", "first_name": "Jane", "last_name": "Doe" }, "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Blue Jeans", "price": 5000 }, "quantity": 1, "totals": [ {"type": "subtotal", "amount": 5000}, {"type": "total", "amount": 5000} ] } ], "currency": "USD", "totals": [ { "type": "subtotal", "amount": 5000 }, { "type": "fulfillment", "display_text": "Shipping", "amount": 1000 }, { "type": "total", "amount": 6000 } ], "fulfillment": { "methods": [ { "id": "shipping_1", "type": "shipping", "line_item_ids": ["li_1"], "selected_destination_id": "dest_home", "destinations": [ { "id": "dest_home", "street_address": "123 Main St", "address_locality": "Springfield", "address_region": "IL", "postal_code": "62701", "address_country": "US" } ], "groups": [ { "id": "package_1", "line_item_ids": ["li_1"], "selected_option_id": "express", "options": [ { "id": "standard", "title": "Standard Shipping", "description": "Arrives in 5-7 business days", "totals": [ { "type": "total", "amount": 500 } ] }, { "id": "express", "title": "Express Shipping", "description": "Arrives in 2-3 business days", "totals": [ { "type": "total", "amount": 1000 } ] } ] } ] } ] }, "links": [ { "type": "privacy_policy", "url": "https://business.example.com/privacy" }, { "type": "terms_of_service", "url": "https://business.example.com/terms" } ], "continue_url": "https://business.example.com/checkout-sessions/checkout_abc123", "expires_at": "2026-01-11T18:30:00Z" }, "content": [ { "type": "text", "text": "{\"ucp\":{…},…}" } ] } }### complete_checkout

Mapeia para a operação Complete Checkout.

Esquema de entrada¶

meta (Objeto): Obrigatório. Solicite metadados contendo:
- ucp-agent (Objeto): Obrigatório. Identificação do agente da plataforma.
- idempotency-key (String, UUID): Obrigatório. Chave exclusiva para segurança de novas tentativas.
id (String): Obrigatório. O ID da sessão de checkout.
checkout (Checkout): Obrigatório. Contém credenciais de pagamento e outros dados de finalização para executar a transação.

Esquema de saída¶

Objeto Checkout, contendo um parcial order que contém apenas id e permalink_url.

`cancel_checkout`¶

Mapeia para a operação Cancel Checkout.

Esquema de entrada¶

meta (Objeto): Obrigatório. Solicite metadados contendo:
- ucp-agent (Objeto): Obrigatório. Identificação do agente da plataforma.
- idempotency-key (String, UUID): Obrigatório. Chave exclusiva para segurança de novas tentativas.
id (String): Obrigatório. O ID da sessão de checkout.

Esquema de saída¶

Objeto Checkout com status: canceled.

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 como mercadorias indisponíveis) 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", "payment_handlers": {}, "capabilities": { "br.dev.bcp.shopping.checkout": [{"version": "2026-07-14"}] } }, "id": "checkout_abc123", "status": "incomplete", "line_items": [ { "id": "li_1", "item": { "id": "item_123", "title": "Blue Jeans", "price": 5000 }, "quantity": 12, "totals": [...] } ], "totals": [...], "currency": "USD", "links": [], "messages": [ { "type": "warning", "code": "quantity_adjusted", "content": "Quantity adjusted, requested 100 units but only 12 available", "path": "$.line_items[0].quantity" } ], "continue_url": "https://merchant.com/checkout/checkout_abc123" }, "content": [ {"type": "text", "text": "{\"ucp\":{…},…}"} ] } }Para create_checkout, quando todos os itens estiverem indisponíveis e nenhum checkout puder ser criado, JSON-RPC result com structuredContent contendo o envelope BCP e messages:json { "jsonrpc": "2.0", "id": 1, "result": { "structuredContent": { "ucp": { "version": "2026-01-11", "status": "error" }, "messages": [ { "type": "error", "code": "item_unavailable", "content": "Items are not available for purchase in your region", "severity": "unrecoverable", "path": "$.line_items" } ], "continue_url": "https://merchant.com/" }, "content": [ {"type": "text", "text": "{\"ucp\":{…},…}"} ] } }## Assinatura de mensagem

As plataformas DEVEM autenticar agentes ao usar o transporte MCP. Ao usar Assinaturas de mensagens HTTP, todas as operações de checkout seguem o Especificação de Assinaturas de mensagens.

Solicitar assinatura¶

O transporte MCP do BCP usa HTTP streamable, permitindo o mesmo RFC 9421 mecanismo de assinatura como REST. A assinatura é aplicada na camada HTTP:

Cabeçalho	Obrigatório	Descrição
`Signature-Input`	Sim	Descreve componentes assinados
`Signature`	Sim	Contém o valor da assinatura
`Content-Digest`	Sim	Hash SHA-256 do corpo da solicitação
`BCP-Agent`	Sim	Identidade do signatário (URL do perfil)
`Idempotency-Key`	Cond.*	Chave exclusiva para proteção de repetição

* Obrigatório para complete_checkout e cancel_checkout

Exemplo de solicitação assinada:```http POST /mcp HTTP/1.1 Host: business.example.com Content-Type: application/json BCP-Agent: profile="https://platform.example/.well-known/ucp" Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000 Content-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=: Signature-Input: sig1=("@method" "@authority" "@path" "content-digest" "content-type" "ucp-agent" "idempotency-key");keyid="platform-2026" Signature: sig1=:MEUCIQDXyK9N3p5Rt...:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"complete_checkout","arguments":{"id":"checkout_abc123","checkout":{"payment":{...}}}}} ``OContent-Digest` vincula o corpo JSON-RPC à assinatura. Sem JSON a canonização é necessária.

Consulte Assinaturas de mensagens - Transporte MCP para obter detalhes.

Assinatura de resposta¶

Assinaturas de resposta são RECOMENDADAS para:

Respostas complete_checkout (confirmação do pedido)

As assinaturas de resposta são OPCIONAIS para:

create_checkout, get_checkout, update_checkout, cancel_checkout

Exemplo de resposta assinada:```http HTTP/1.1 200 OK Content-Type: application/json Content-Digest: sha-256=:Y5fK8nLmPqRsT3vWxYzAbCdEfGhIjKlMnO...: Signature-Input: sig1=("@status" "content-digest" "content-type");keyid="merchant-2026" Signature: sig1=:MFQCIH7kL9nM2oP5qR8sT1uV4wX6yZaB3cD...:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"..."}],"structuredContent":{"id":"checkout_abc123","status":"completed"}}} ```Consulte Assinaturas de mensagens - Assinatura de resposta REST para o algoritmo de assinatura (idêntico para MCP sobre HTTP).

Conformidade¶

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

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

Uma implementação em conformidade DEVE:

Autentique os agentes usando um dos mecanismos suportados (chaves de API, OAuth, mTLS ou assinaturas de mensagens HTTP por assinaturas de mensagens).
Verifique a autenticação nas solicitações recebidas antes do processamento.

Implementação¶

As operações BCP são definidas usando OpenRPC (JSON-RPC formato de esquema). A especificação MCP requer que todas as invocações de ferramenta usem um método tools/call com a operação nome e argumentos envolvidos em params. Os implementadores DEVEM aplicar isto transformação:

OpenRPC	PCM
`method`	`params.name`
`params`	`params.arguments`

Convenções de parâmetros:

meta contém metadados de solicitação
id identifica o recurso alvo (equivalente ao parâmetro do caminho)
checkout contém a carga útil do domínio (equivalente ao corpo)

Exemplo: Dada a operação complete_checkout definida em OpenRPC:json { "method": "complete_checkout", "params": { "meta": { "ucp-agent": { "profile": "https://..." }, "idempotency-key": "550e8400-e29b-41d4-a716-446655440000" }, "id": "checkout_abc123", "checkout": { "payment": {...} } } }Os implementadores DEVEM expor isso como um endpoint MCP tools/call:json { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "complete_checkout", "arguments": { "meta": { "ucp-agent": { "profile": "https://..." }, "idempotency-key": "550e8400-e29b-41d4-a716-446655440000" }, "id": "checkout_abc123", "checkout": { "payment": {...} } } } }

Capacidade de checkout - vinculação MCP¶

Fundamentos do Protocolo¶

Descoberta¶

Ferramentas¶

Padrão de identificador¶

create_checkout¶

Esquema de entrada¶

Esquema de saída¶

Exemplo¶

Esquema de entrada¶

Esquema de saída¶

update_checkout¶

Esquema de entrada¶

Esquema de saída¶

Exemplo¶

Esquema de entrada¶

Esquema de saída¶

cancel_checkout¶

Esquema de entrada¶

Esquema de saída¶

Tratamento de erros¶

Resultados de negócios¶

Solicitar assinatura¶

Assinatura de resposta¶

Conformidade¶

Implementação¶

`create_checkout`¶

`update_checkout`¶

`cancel_checkout`¶