Capacidade de pedido - vinculação MCP

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

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.order": [
        {
          "version": "2026-07-28",
          "spec": "https://bcp.dev.br/draft/specification/order",
          "schema": "https://bcp.dev.br/draft/schemas/shopping/order.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": "get_order",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/.well-known/bcp"
        }
      },
      "id": "order_abc123"
    }
  }
}

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.

Ferramenta	Operação	Descrição
get_order	Obter pedido	Obtenha o estado atual de um pedido.

get_order

Mapeia para a operação Obter pedido. Retorna o instantâneo do estado atual de um pedido.

Esquema de entrada

• meta (Objeto obrigatório): Solicita metadados com ucp-agent.profile.
• id (String, obrigatório): O ID do pedido.

Esquema de saída

Nome	Tipo	Obrigatório	Descrição
ucp	any	Sim	Metadados BCP para respostas de order. Não são necessários payment handlers após a compra.
id	string	Sim	Identificador único do pedido.
label	string	Não	Rótulo legível por humanos para identificar o pedido. DEVE ser fornecido apenas pela empresa.
checkout_id	string	Sim	ID do checkout associado para conciliação.
permalink_url	string	Sim	Permalink para acessar o pedido no site do lojista.
line_items	Array[Order Line Item]	Sim	Itens de linha representando o que foi comprado — podem mudar após o pedido por meio de edições ou trocas.
fulfillment	object	Sim	Dados de fulfillment: as expectativas do comprador e o que de fato ocorreu.
adjustments	Array[Adjustment]	Não	Eventos pós-pedido (reembolsos, devoluções, créditos, disputas, cancelamentos, etc.) que existem independentemente do fulfillment.
currency	string	Sim	Código de moeda ISO 4217. DEVE corresponder à moeda da sessão de checkout de origem.
totals	Totals	Sim	Diferentes totais do pedido.
messages	Array[Message]	Não	Mensagens de resultado da empresa (erros, avisos, informativas). Presentes quando a empresa precisa comunicar status ou problemas à plataforma.
attribution	Attribution	Não	Snapshot da atribuição associada ao checkout de origem. Somente leitura no pedido.

Exemplo

SolicitaçãoRespostaNão encontradoNão autorizado

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_order",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/.well-known/bcp"
        }
      },
      "id": "order_abc123"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "capabilities": {
          "br.dev.bcp.shopping.order": [{"version": "2026-07-28"}]
        }
      },
      "id": "order_abc123",
      "checkout_id": "checkout_xyz789",
      "permalink_url": "https://business.example.com/orders/abc123",
      "currency": "BRL",
      "line_items": [
        {
          "id": "li_shoes",
          "item": { "id": "prod_shoes", "title": "Running Shoes", "price": 3000 },
          "quantity": { "total": 1, "fulfilled": 1 },
          "totals": [
            {"type": "subtotal", "amount": 3000},
            {"type": "total", "amount": 3000}
          ],
          "status": "fulfilled"
        }
      ],
      "fulfillment": {
        "expectations": [
          {
            "id": "exp_1",
            "line_items": [{ "id": "li_shoes", "quantity": 1 }],
            "method_type": "shipping",
            "destination": {
              "street_address": "Rua das Flores, 123",
              "address_locality": "São Paulo",
              "address_region": "SP",
              "address_country": "BR",
              "postal_code": "01310-100"
            },
            "description": "Entregue"
          }
        ],
        "events": [
          {
            "id": "evt_1",
            "occurred_at": "2026-01-08T10:30:00Z",
            "type": "delivered",
            "line_items": [{ "id": "li_shoes", "quantity": 1 }],
            "tracking_number": "BR123456784BR",
            "tracking_url": "https://rastreamento.correios.com.br/app/index.php?objetos=BR123456784BR",
            "description": "Entregue na portaria"
          }
        ]
      },
      "adjustments": [],
      "totals": [
        { "type": "subtotal", "amount": 3000 },
        { "type": "fulfillment", "amount": 800 },
        { "type": "tax", "amount": 304 },
        { "type": "total", "amount": 4104 }
      ]
    },
    "content": [
      {
        "type": "text",
        "text": "{\"ucp\":{…},…}"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "status": "error",
        "capabilities": {
          "br.dev.bcp.shopping.order": [{"version": "2026-07-28"}]
        }
      },
      "messages": [
        {
          "type": "error",
          "code": "not_found",
          "severity": "unrecoverable",
          "content": "Order not found."
        }
      ]
    },
    "content": [
      {
        "type": "text",
        "text": "Order not found."
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "2026-07-28",
        "status": "error",
        "capabilities": {
          "br.dev.bcp.shopping.order": [{"version": "2026-07-28"}]
        }
      },
      "messages": [
        {
          "type": "error",
          "code": "unauthorized",
          "severity": "unrecoverable",
          "content": "Not authorized to access this order."
        }
      ]
    },
    "content": [
      {
        "type": "text",
        "text": "Not authorized to access this order."
      }
    ]
  }
}

Tratamento de erros

Quando a empresa não consegue devolver um pedido, a resposta inclui uma matriz messages que descreve o resultado. Plataformas DEVEM verificar messages antes de acessar os campos do pedido.

Conformidade

Plataformas que implementam a vinculação MCP:

• DEVE incluir meta.ucp-agent.profile em todas as solicitações
• DEVE verificar o array messages nas respostas antes de acessar os dados do pedido
• DEVE delegar à empresa, via permalink_url, a experiência oficial do pedido — o site da empresa é a fonte da verdade para os detalhes do pedido e operações pós-compra

Empresas que implementam a vinculação MCP:

• DEVE implementar a ferramenta get_order de acordo com Esquema OpenRPC

Consulte Capacidade do pedido - Diretrizes para requisitos de nível de capacidade que se aplicam a todos os transportes.