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": "draft",
    "services": {
      "dev.ucp.shopping": [
        {
          "version": "draft",
          "spec": "https://ucp.dev/draft/specification/overview",
          "transport": "mcp",
          "schema": "https://ucp.dev/draft/services/shopping/mcp.openrpc.json",
          "endpoint": "https://business.example.com/ucp/mcp"
        }
      ]
    },
    "capabilities": {
      "dev.ucp.shopping.checkout": [
        {
          "version": "draft",
          "spec": "https://ucp.dev/draft/specification/checkout",
          "schema": "https://ucp.dev/draft/schemas/shopping/checkout.json"
        }
      ],
      "dev.ucp.shopping.cart": [
        {
          "version": "draft",
          "spec": "https://ucp.dev/draft/specification/cart",
          "schema": "https://ucp.dev/draft/schemas/shopping/cart.json"
        }
      ]
    }
  }
}

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. Platforms MAY include additional metadata fields.

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. The cart object in the request payload MUST NOT contain an id field.
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.

Input Schema¶

Name	Type	Required	Description
line_items	Array[Line Item]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.

Output Schema¶

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item Response]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.
currency	string	Yes	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Yes	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages	Array[Message]	No	Validation messages, warnings, or informational notices.
links	Array[Link]	No	Optional merchant links (policies, FAQs).
continue_url	string	No	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	No	Cart expiry timestamp (RFC 3339). Optional.

Example¶

RequestResponseError Response

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "draft",
        "capabilities": {
          "dev.ucp.shopping.checkout": [{"version": "draft"}],
          "dev.ucp.shopping.cart": [{"version": "draft"}]
        }
      },
      "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"
    },
    "content": [
      {
        "type": "text",
        "text": "{\"ucp\":{...},\"id\":\"cart_abc123\",...}"
      }
    ]
  }
}

All items out of stock — no cart resource is created:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": { "version": "2026-01-15", "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\":{...},\"messages\":[...]}"}
    ]
  }
}

`get_cart`¶

Maps to the Get Cart operation.

Input Schema¶

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

Output Schema¶

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item Response]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.
currency	string	Yes	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Yes	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages	Array[Message]	No	Validation messages, warnings, or informational notices.
links	Array[Link]	No	Optional merchant links (policies, FAQs).
continue_url	string	No	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	No	Cart expiry timestamp (RFC 3339). Optional.

Example¶

RequestResponseNot Found

{
  "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": "draft",
        "capabilities": {
          "dev.ucp.shopping.checkout": [{"version": "draft"}],
          "dev.ucp.shopping.cart": [{"version": "draft"}]
        }
      },
      "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"
    },
    "content": [
      {
        "type": "text",
        "text": "{\"ucp\":{...},\"id\":\"cart_abc123\",...}"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "draft",
        "capabilities": {
          "dev.ucp.shopping.cart": [{"version": "draft"}]
        }
      },
      "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\":{...},\"messages\":[...],\"continue_url\":\"...\"}"
      }
    ]
  }
}

`update_cart`¶

Maps to the Update Cart operation.

Input Schema¶

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

Name	Type	Required	Description
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.

Output Schema¶

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item Response]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.
currency	string	Yes	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Yes	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages	Array[Message]	No	Validation messages, warnings, or informational notices.
links	Array[Link]	No	Optional merchant links (policies, FAQs).
continue_url	string	No	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	No	Cart expiry timestamp (RFC 3339). Optional.

Example¶

RequestResponse

{
  "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": "US",
          "address_region": "CA",
          "postal_code": "94105"
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "draft",
        "capabilities": {
          "dev.ucp.shopping.checkout": [{"version": "draft"}],
          "dev.ucp.shopping.cart": [{"version": "draft"}]
        }
      },
      "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": "USD",
      "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\":{...},\"id\":\"cart_abc123\",...}"
      }
    ]
  }
}

`cancel_cart`¶

Maps to the Cancel Cart operation.

Input Schema¶

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

Output Schema¶

Name	Type	Required	Description
ucp	any	Yes	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Yes	Unique cart identifier.
line_items	Array[Line Item Response]	Yes	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	No	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	No	Environment data provided by the platform to support authorization and abuse prevention. Values MUST NOT be buyer-asserted claims — platforms provide signals based on direct observation or independently verifiable third-party attestations. All signal keys MUST use reverse-domain naming to ensure provenance and prevent collisions when multiple extensions contribute to the shared namespace.
attribution	Attribution	No	Platform-emitted referral and conversion-event context — campaign identifiers, click IDs, source/medium markers, etc. The same parameters platforms communicate via URL query parameters in browser-based flows.
buyer	Buyer	No	Optional buyer information for personalized estimates.
currency	string	Yes	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Yes	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
messages	Array[Message]	No	Validation messages, warnings, or informational notices.
links	Array[Link]	No	Optional merchant links (policies, FAQs).
continue_url	string	No	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	No	Cart expiry timestamp (RFC 3339). Optional.

Example¶

RequestResponse

{
  "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": "draft",
        "capabilities": {
          "dev.ucp.shopping.checkout": [{"version": "draft"}],
          "dev.ucp.shopping.cart": [{"version": "draft"}]
        }
      },
      "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"
    },
    "content": [
      {
        "type": "text",
        "text": "{\"ucp\":{...},\"id\":\"cart_abc123\",...}"
      }
    ]
  }
}

Error Handling¶

UCP distinguishes between protocol errors and business outcomes. See the Core Specification for the complete error code registry and transport binding examples.

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.

Business Outcomes¶

Business outcomes (including not found and validation errors) are returned as JSON-RPC result with structuredContent containing the UCP envelope and messages:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "draft",
        "capabilities": {
          "dev.ucp.shopping.cart": [{"version": "draft"}]
        }
      },
      "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\":{...},\"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.

Cart Capability - MCP Binding¶

Protocol Fundamentals¶

Discovery¶

Request Metadata¶

Tools¶

Identifier Pattern¶

create_cart¶

Input Schema¶

Output Schema¶

Example¶

get_cart¶

Input Schema¶

Output Schema¶

Example¶

update_cart¶

Input Schema¶

Output Schema¶

Example¶

cancel_cart¶

Input Schema¶

Output Schema¶

Example¶

Error Handling¶

Business Outcomes¶

Conformance¶

`create_cart`¶

`get_cart`¶

`update_cart`¶

`cancel_cart`¶