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

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

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	Requirement	Description
line_items	Array[Line Item]	Required	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	Optional	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	Optional	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	Optional	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	Optional	Optional buyer information for personalized estimates.

Output Schema¶

Name	Type	Requirement	Description
ucp	UCP Cart Response Schema	Required	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Required	Unique cart identifier.
line_items	Array[Line Item Response]	Required	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	Optional	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	Optional	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	Optional	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	Optional	Optional buyer information for personalized estimates.
currency	string	Required	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Required	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
actions	Actions	Optional	Outstanding extension-defined Actions for this cart.
messages	Array[Message]	Optional	Validation messages, warnings, or informational notices.
links	Array[Link]	Optional	Optional merchant links (policies, FAQs).
policies	Array[Policy]	Optional	Policies (e.g., return/refund terms) that apply to the items in this cart. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.
continue_url	string	Optional	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	Optional	Cart expiry timestamp (RFC 3339). Optional.

Example¶

RequestResponseError Response

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": "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\":{…},…}"
      }
    ]
  }
}

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

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

Maps to the Get Cart operation.

Input Schema¶

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

Output Schema¶

Name	Type	Requirement	Description
ucp	UCP Cart Response Schema	Required	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Required	Unique cart identifier.
line_items	Array[Line Item Response]	Required	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	Optional	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	Optional	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	Optional	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	Optional	Optional buyer information for personalized estimates.
currency	string	Required	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Required	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
actions	Actions	Optional	Outstanding extension-defined Actions for this cart.
messages	Array[Message]	Optional	Validation messages, warnings, or informational notices.
links	Array[Link]	Optional	Optional merchant links (policies, FAQs).
policies	Array[Policy]	Optional	Policies (e.g., return/refund terms) that apply to the items in this cart. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.
continue_url	string	Optional	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	Optional	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\":{…},…}"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": {
        "version": "draft",
        "status": "error",
        "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\":{…},…}"
      }
    ]
  }
}

`update_cart`¶

Maps to the Update Cart operation.

Input Schema¶

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

Name	Type	Requirement	Description
line_items	Array[Line Item]	Required	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	Optional	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	Optional	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	Optional	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	Optional	Optional buyer information for personalized estimates.

Output Schema¶

Name	Type	Requirement	Description
ucp	UCP Cart Response Schema	Required	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Required	Unique cart identifier.
line_items	Array[Line Item Response]	Required	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	Optional	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	Optional	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	Optional	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	Optional	Optional buyer information for personalized estimates.
currency	string	Required	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Required	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
actions	Actions	Optional	Outstanding extension-defined Actions for this cart.
messages	Array[Message]	Optional	Validation messages, warnings, or informational notices.
links	Array[Link]	Optional	Optional merchant links (policies, FAQs).
policies	Array[Policy]	Optional	Policies (e.g., return/refund terms) that apply to the items in this cart. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.
continue_url	string	Optional	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	Optional	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\":{…},…}"
      }
    ]
  }
}

`cancel_cart`¶

Maps to the Cancel Cart operation.

Input Schema¶

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

Output Schema¶

Name	Type	Requirement	Description
ucp	UCP Cart Response Schema	Required	UCP metadata for cart responses. No payment handlers needed pre-checkout.
id	string	Required	Unique cart identifier.
line_items	Array[Line Item Response]	Required	Cart line items. Same structure as checkout. Full replacement on update.
context	Context	Optional	Buyer signals for localization (country, region, postal_code). Merchant uses for pricing, availability, currency. Falls back to geo-IP if omitted.
signals	Signals	Optional	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	Optional	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	Optional	Optional buyer information for personalized estimates.
currency	string	Required	ISO 4217 currency code. Determined by merchant based on context or geo-IP.
totals	Totals	Required	Estimated cost breakdown. May be partial if shipping/tax not yet calculable.
actions	Actions	Optional	Outstanding extension-defined Actions for this cart.
messages	Array[Message]	Optional	Validation messages, warnings, or informational notices.
links	Array[Link]	Optional	Optional merchant links (policies, FAQs).
policies	Array[Policy]	Optional	Policies (e.g., return/refund terms) that apply to the items in this cart. `applies_to` targets are relative to the response root; when absent or empty, refer to the URLs in `links[]`.
continue_url	string	Optional	URL for cart handoff and session recovery. Enables sharing and human-in-the-loop flows.
expires_at	string	Optional	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\":{…},…}"
      }
    ]
  }
}

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",
        "status": "error",
        "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\":{…},…}"}
    ]
  }
}

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`¶