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/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.order": [
{
"version": "2026-07-14",
"spec": "https://bcp.dev.br/2026-07-14/specification/order",
"schema": "https://bcp.dev.br/2026-07-14/schemas/shopping/order.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": "get_order",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://platform.example/.well-known/ucp"
}
},
"id": "order_abc123"
}
}
}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.
| Ferramenta | Operação | Descrição |
|---|---|---|
get_order |
Obter pedido | Obtenha o estado atual de um pedido. |
get_order¶
Mapeia para a operação Get Order. Retorna o instantâneo do estado atual de um pedido.
Esquema de entrada¶
meta(Objeto obrigatório): Solicita metadados comucp-agent.profile.id(String, obrigatório): O ID do pedido.
Esquema de saída¶
| Name | Type | Required | Description |
|---|---|---|---|
| ucp | any | Yes | UCP metadata for order responses. No payment handlers needed post-purchase. |
| id | string | Yes | Unique order identifier. |
| label | string | No | Human-readable label for identifying the order. MUST only be provided by the business. |
| checkout_id | string | Yes | Associated checkout ID for reconciliation. |
| permalink_url | string | Yes | Permalink to access the order on merchant site. |
| line_items | Array[Order Line Item] | Yes | Line items representing what was purchased — can change post-order via edits or exchanges. |
| fulfillment | object | Yes | Fulfillment data: buyer expectations and what actually happened. |
| adjustments | Array[Adjustment] | No | Post-order events (refunds, returns, credits, disputes, cancellations, etc.) that exist independently of fulfillment. |
| currency | string | Yes | ISO 4217 currency code. MUST match the currency from the originating checkout session. |
| totals | Totals | Yes | Different totals for the order. |
| messages | Array[Message] | No | Business outcome messages (errors, warnings, informational). Present when the business needs to communicate status or issues to the platform. |
| attribution | Attribution | No | Snapshot of the attribution associated with the originating checkout. Read-only on the order. |
Exemplo¶
=== "Solicitação"json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "get_order",
"arguments": {
"meta": {
"ucp-agent": {
"profile": "https://platform.example/.well-known/ucp"
}
},
"id": "order_abc123"
}
}
}=== "Resposta"json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-07-14",
"capabilities": {
"br.dev.bcp.shopping.order": [{"version": "2026-07-14"}]
}
},
"id": "order_abc123",
"checkout_id": "checkout_xyz789",
"permalink_url": "https://business.example.com/orders/abc123",
"currency": "USD",
"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": "123 Main St",
"address_locality": "Austin",
"address_region": "TX",
"address_country": "US",
"postal_code": "78701"
},
"description": "Delivered"
}
],
"events": [
{
"id": "evt_1",
"occurred_at": "2026-01-08T10:30:00Z",
"type": "delivered",
"line_items": [{ "id": "li_shoes", "quantity": 1 }],
"tracking_number": "1Z999AA10123456784",
"tracking_url": "https://ups.com/track/1Z999AA10123456784",
"description": "Delivered to front door"
}
]
},
"adjustments": [],
"totals": [
{ "type": "subtotal", "amount": 3000 },
{ "type": "fulfillment", "amount": 800 },
{ "type": "tax", "amount": 304 },
{ "type": "total", "amount": 4104 }
]
},
"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.order": [{"version": "2026-07-14"}]
}
},
"messages": [
{
"type": "error",
"code": "not_found",
"severity": "unrecoverable",
"content": "Order not found."
}
]
},
"content": [
{
"type": "text",
"text": "Order not found."
}
]
}
}=== "Não autorizado"json
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"structuredContent": {
"ucp": {
"version": "2026-07-14",
"status": "error",
"capabilities": {
"br.dev.bcp.shopping.order": [{"version": "2026-07-14"}]
}
},
"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 um messages
matriz que descreve o resultado. Plataformas DEVEM verificar messages antes
acessando campos de pedidos.
Conformidade¶
Plataformas que implementam a vinculação MCP:
- DEVE incluir
meta.ucp-agent.profileem todas as solicitações - DEVE verificar o array
messagesnas respostas antes de acessar os dados do pedido - DEVE delegar à empresa via
permalink_urlpara autoridade experiência 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_orderde acordo com Esquema OpenRPC
Consulte Capacidade do pedido - Diretrizes para requisitos de nível de capacidade que se aplicam a todos os transportes.