Capacidade do carrinho - vinculação MCP¶

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

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.checkout": [
        {
          "version": "2026-07-28",
          "spec": "https://bcp.dev.br/draft/specification/checkout",
          "schema": "https://bcp.dev.br/draft/schemas/shopping/checkout.json"
        }
      ],
      "br.dev.bcp.shopping.cart": [
        {
          "version": "2026-07-28",
          "spec": "https://bcp.dev.br/draft/specification/cart",
          "schema": "https://bcp.dev.br/draft/schemas/shopping/cart.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": "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 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:

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 objeto cart 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 na 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	Obtenha 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¶

Nome	Tipo	Obrigatório	Descrição
line_items	Array[Line Item]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.

Esquema de saída¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de cart. Não são necessários payment handlers antes do checkout.
id	string	Sim	Identificador único do carrinho.
line_items	Array[Line Item Response]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.
currency	string	Sim	Código de moeda ISO 4217. Determinado pelo lojista com base no contexto ou em geo-IP.
totals	Totals	Sim	Detalhamento estimado de custos. Pode ser parcial se frete/imposto ainda não forem calculáveis.
messages	Array[Message]	Não	Mensagens de validação, avisos ou notas informativas.
links	Array[Link]	Não	Links opcionais do lojista (políticas, FAQs).
continue_url	string	Não	URL para handoff do carrinho e recuperação de sessão. Habilita compartilhamento e fluxos com humano no circuito (human-in-the-loop).
expires_at	string	Não	Timestamp de expiração do carrinho (RFC 3339). Opcional.

Exemplo¶

SolicitaçãoRespostaResposta de erro

href="#__codelineno-2-1">{ "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": "BR", "address_region": "SP", "postal_code": "01310-100" } } } } }

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

Todos os itens fora de estoque — nenhum recurso de carrinho é criado:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": { "version": "2026-07-28", "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¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de cart. Não são necessários payment handlers antes do checkout.
id	string	Sim	Identificador único do carrinho.
line_items	Array[Line Item Response]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.
currency	string	Sim	Código de moeda ISO 4217. Determinado pelo lojista com base no contexto ou em geo-IP.
totals	Totals	Sim	Detalhamento estimado de custos. Pode ser parcial se frete/imposto ainda não forem calculáveis.
messages	Array[Message]	Não	Mensagens de validação, avisos ou notas informativas.
links	Array[Link]	Não	Links opcionais do lojista (políticas, FAQs).
continue_url	string	Não	URL para handoff do carrinho e recuperação de sessão. Habilita compartilhamento e fluxos com humano no circuito (human-in-the-loop).
expires_at	string	Não	Timestamp de expiração do carrinho (RFC 3339). Opcional.

Exemplo¶

SolicitaçãoRespostaNão encontrado

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

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

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

Nome	Tipo	Obrigatório	Descrição
id	string	Sim	Identificador único do carrinho.
line_items	Array[Line Item]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.

Esquema de saída¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de cart. Não são necessários payment handlers antes do checkout.
id	string	Sim	Identificador único do carrinho.
line_items	Array[Line Item Response]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.
currency	string	Sim	Código de moeda ISO 4217. Determinado pelo lojista com base no contexto ou em geo-IP.
totals	Totals	Sim	Detalhamento estimado de custos. Pode ser parcial se frete/imposto ainda não forem calculáveis.
messages	Array[Message]	Não	Mensagens de validação, avisos ou notas informativas.
links	Array[Link]	Não	Links opcionais do lojista (políticas, FAQs).
continue_url	string	Não	URL para handoff do carrinho e recuperação de sessão. Habilita compartilhamento e fluxos com humano no circuito (human-in-the-loop).
expires_at	string	Não	Timestamp de expiração do carrinho (RFC 3339). Opcional.

Exemplo¶

SolicitaçãoResposta

{
  "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": "BR",
          "address_region": "SP",
          "postal_code": "01310-100"
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.checkout": [{"version": "2026-07-28"}],
          "br.dev.bcp.shopping.cart": [{"version": "2026-07-28"}]
        }
      },
      "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": "BRL",
      "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¶

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de cart. Não são necessários payment handlers antes do checkout.
id	string	Sim	Identificador único do carrinho.
line_items	Array[Line Item Response]	Sim	Itens de linha do carrinho. Mesma estrutura do checkout. Substituição total na atualização.
context	Context	Não	Sinais do comprador para localização (country, region, postal_code). O lojista os usa para preço, disponibilidade e moeda. Recorre a geo-IP se omitidos.
signals	Signals	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	Attribution	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.
buyer	Buyer	Não	Informações opcionais do comprador para estimativas personalizadas.
currency	string	Sim	Código de moeda ISO 4217. Determinado pelo lojista com base no contexto ou em geo-IP.
totals	Totals	Sim	Detalhamento estimado de custos. Pode ser parcial se frete/imposto ainda não forem calculáveis.
messages	Array[Message]	Não	Mensagens de validação, avisos ou notas informativas.
links	Array[Link]	Não	Links opcionais do lojista (políticas, FAQs).
continue_url	string	Não	URL para handoff do carrinho e recuperação de sessão. Habilita compartilhamento e fluxos com humano no circuito (human-in-the-loop).
expires_at	string	Não	Timestamp de expiração do carrinho (RFC 3339). Opcional.

Exemplo¶

SolicitaçãoResposta

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.checkout": [{"version": "2026-07-28"}],
          "br.dev.bcp.shopping.cart": [{"version": "2026-07-28"}]
        }
      },
      "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": "BRL",
      "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 a especificação principal para o registro completo de códigos de erro e exemplos de vinculação de transporte.

Erros de protocolo: falhas no nível de transporte (autenticação, limitação de taxa, indisponibilidade) que impedem o processamento da solicitação. Retornadas como JSON-RPC error com código -32000 (ou -32001 para erros de descoberta).
Resultados de negócios: resultados em nível de aplicação do processamento bem-sucedido da solicitação, retornados 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:

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

Implementar o protocolo JSON-RPC 2.0 corretamente.
Fornecer todas as ferramentas básicas do carrinho definidas nesta especificação.
Retornar erros de acordo com a especificação principal.
Retornar os resultados de negócios como JSON-RPC result com envelope BCP e matriz messages.
Validar as entradas da ferramenta em relação aos esquemas BCP.
Suportar transporte HTTP com streaming.

Capacidade do carrinho - vinculação MCP¶

Fundamentos do Protocolo¶

Descoberta¶

Solicitar metadados¶

Ferramentas¶

Padrão de identificador¶

create_cart¶

Esquema de entrada¶

Esquema de saída¶

Exemplo¶

get_cart¶

Esquema de entrada¶

Esquema de saída¶

Exemplo¶

update_cart¶

Esquema de entrada¶

Esquema de saída¶

Exemplo¶

cancel_cart¶

Esquema de entrada¶

Esquema de saída¶

Exemplo¶

Tratamento de erros¶

Resultados de negócios¶

Conformidade¶

`create_cart`¶

`get_cart`¶

`update_cart`¶

`cancel_cart`¶