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",
        "mcp": {
          "schema": "https://ucp.dev/draft/services/shopping/mcp.openrpc.json",
          "endpoint": "https://business.example.com/ucp/mcp"
        }
      }
    },
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "draft",
        "spec": "https://ucp.dev/draft/specification/checkout",
        "schema": "https://ucp.dev/draft/schemas/shopping/checkout.json"
      },
      {
        "name": "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.
buyer	Buyer	No	Optional buyer information for personalized estimates.

Output Schema¶

Name	Type	Required	Description
ucp	Ucp Response Cart Schema	Yes	Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
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.
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	Array[Total Response]	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": {
      "cart": {
        "ucp": {
          "version": "draft",
          "capabilities": [
            {
              "name": "dev.ucp.shopping.checkout",
              "version": "draft"
            },
            {
              "name": "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": "{\"cart\":{\"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	Ucp Response Cart Schema	Yes	Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
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.
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	Array[Total Response]	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": {
      "cart": {
        "ucp": {
          "version": "draft",
          "capabilities": [
            {
              "name": "dev.ucp.shopping.checkout",
              "version": "draft"
            },
            {
              "name": "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": "{\"cart\":{\"ucp\":{...},\"id\":\"cart_abc123\",...}}"
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "cart": {
        "ucp": {
          "version": "draft",
          "capabilities": [
            {
              "name": "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.
buyer	Buyer	No	Optional buyer information for personalized estimates.

Output Schema¶

Name	Type	Required	Description
ucp	Ucp Response Cart Schema	Yes	Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
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.
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	Array[Total Response]	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": {
      "cart": {
        "ucp": {
          "version": "draft",
          "capabilities": [
            {
              "name": "dev.ucp.shopping.checkout",
              "version": "draft"
            },
            {
              "name": "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": "{\"cart\":{\"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	Ucp Response Cart Schema	Yes	Protocol metadata for discovery profiles and responses. Uses slim schema pattern with context-specific required fields.
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.
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	Array[Total Response]	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": {
      "cart": {
        "ucp": {
          "version": "draft",
          "capabilities": [
            {
              "name": "dev.ucp.shopping.checkout",
              "version": "draft"
            },
            {
              "name": "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": "{\"cart\":{\"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": {
      "cart": {
        "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`¶