Cart Capability - MCP Binding

This document specifies the Model Context Protocol (MCP) binding for the Cart Capability.

Protocol Fundamentals

Discovery

Businesses advertise MCP transport availability through their UCP profile at /.well-known/ucp.

{
  "ucp": {
    "version": "2026-01-11",
    "services": {
      "dev.ucp.shopping": {
        "version": "2026-01-11",
        "mcp": {
          "schema": "https://ucp.dev/2026-01-11/services/shopping/mcp.openrpc.json",
          "endpoint": "https://business.example.com/ucp/mcp"
        }
      }
    },
    "capabilities": [
      {"name": "dev.ucp.shopping.checkout", "version": "2026-01-11"},
      {"name": "dev.ucp.shopping.cart", "version": "2026-01-11"}
    ]
  }
}

Request Metadata

MCP clients MUST include a meta object in every request containing protocol metadata:

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

The meta["ucp-agent"] field is required on all requests to enable capability negotiation.

Tools

UCP Capabilities map 1:1 to MCP Tools.

Identifier Pattern

MCP tools separate resource identification from payload data:

Requests: For operations on existing carts (get, update, cancel), a top-level id parameter identifies the target resource.
Responses: All responses include cart.id as part of the full resource state.
Create: The create_cart operation does not require an id in the request, and the response includes the newly assigned cart.id.

Tool	Operation	Description
`create_cart`	Create Cart	Create a cart session.
`get_cart`	Get Cart	Get a cart session.
`update_cart`	Update Cart	Update a cart session.
`cancel_cart`	Cancel Cart	Cancel a cart session.

`create_cart`

Maps to the Create Cart operation.

Example

=== “Request”

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

=== “Response”

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "cart": {
        "ucp": {
          "version": "2026-01-11",
          "capabilities": [
            {"name": "dev.ucp.shopping.checkout", "version": "2026-01-11"},
            {"name": "dev.ucp.shopping.cart", "version": "2026-01-11"}
          ]
        },
        "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"
      }
    }
  }
}
```

`get_cart`

Maps to the Get Cart operation.

Input

id (String, required): The ID of the cart session.

`update_cart`

Maps to the Update Cart operation.

Input

id (String, required): The ID of the cart session to update.

`cancel_cart`

Maps to the Cancel Cart operation.

Input

id (String, required): The ID of the cart session.

Error Handling

UCP distinguishes between protocol errors and business outcomes.

Protocol errors: Transport-level failures (authentication, rate limiting, unavailability) that prevent request processing. Returned as JSON-RPC error with code -32000 (or -32001 for discovery errors).
Business outcomes: Application-level results from successful request processing, returned as JSON-RPC result with UCP envelope and messages.

Conformance

A conforming MCP transport implementation MUST:

Implement JSON-RPC 2.0 protocol correctly.
Provide all core cart tools defined in this specification.
Return errors per the Core Specification.
Return business outcomes as JSON-RPC result with UCP envelope and messages array.
Validate tool inputs against UCP schemas.
Support HTTP transport with streaming.