Checkout Capability - MCP Binding¶

This document specifies the Model Context Protocol (MCP) binding for the Checkout 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.fulfillment": [
        {
          "version": "draft",
          "spec": "https://ucp.dev/draft/specification/fulfillment",
          "schema": "https://ucp.dev/draft/schemas/shopping/fulfillment.json",
          "extends": "dev.ucp.shopping.checkout"
        }
      ]
    },
    "payment_handlers": {
      "com.example.vendor.delegate_payment": [
        {
          "id": "handler_1",
          "version": "draft",
          "spec": "https://example.vendor.com/specs/delegate-payment",
          "schema": "https://example.vendor.com/schemas/delegate-payment-config.json",
          "available_instruments": [
            {"type": "card", "constraints": {"brands": ["visa", "mastercard"]}}
          ],
          "config": {}
        }
      ]
    }
  }
}

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_checkout",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/shopping-agent.json"
        },
        "idempotency-key": "550e8400-e29b-41d4-a716-446655440000"
      },
      "checkout": { ... }
    }
  }
}

The meta["ucp-agent"] field is required on all requests to enable capability negotiation. The complete_checkout and cancel_checkout operations also require meta["idempotency-key"] for retry safety. 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 checkouts (get, update, complete, cancel), a top-level id parameter identifies the target resource. The checkout object in the request payload MUST NOT contain an id field.
Responses: All responses include checkout.id as part of the full resource state.
Create: The create_checkout operation does not require an id in the request, and the response includes the newly assigned checkout.id.

Tool	Operation	Description
`create_checkout`	Create Checkout	Create a checkout session.
`get_checkout`	Get Checkout	Get a checkout session.
`update_checkout`	Update Checkout	Update a checkout session.
`complete_checkout`	Complete Checkout	Place the order.
`cancel_checkout`	Cancel Checkout	Cancel a checkout session.

`create_checkout`¶

Maps to the Create Checkout operation.

Input Schema¶

checkout (Checkout): Required. Contains the initial checkout session data and optional extensions.
- Extensions (Optional):
  - dev.ucp.shopping.buyer_consent: Buyer Consent
  - dev.ucp.shopping.fulfillment: Fulfillment
  - dev.ucp.shopping.discount: Discount
  - dev.ucp.shopping.ap2_mandate: AP2 Mandates

Output Schema¶

Checkout object.

Example¶

RequestResponseError Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_checkout",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
        }
      },
      "checkout": {
        "buyer": {
          "email": "jane.doe@example.com",
          "first_name": "Jane",
          "last_name": "Doe"
        },
        "line_items": [
          {
            "item": {
              "id": "item_123"
            },
            "quantity": 1
          }
        ],
        "currency": "USD",
        "fulfillment": {
          "methods": [
            {
              "type": "shipping",
              "destinations": [
                {
                  "street_address": "123 Main St",
                  "address_locality": "Springfield",
                  "address_region": "IL",
                  "postal_code": "62701",
                  "address_country": "US"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "checkout": {
        "ucp": {
          "version": "draft",
          "capabilities": {
            "dev.ucp.shopping.checkout": [
              {"version": "draft"}
            ],
            "dev.ucp.shopping.fulfillment": [
              {"version": "draft"}
            ]
          },
          "payment_handlers": {
            "com.example.vendor.delegate_payment": [
              {"id": "handler_1", "version": "draft", "available_instruments": [{"type": "card"}], "config": {}}
            ]
          }
        },
        "id": "checkout_abc123",
        "status": "incomplete",
        "buyer": {
          "email": "jane.doe@example.com",
          "first_name": "Jane",
          "last_name": "Doe"
        },
        "line_items": [
          {
            "id": "item_123",
            "item": {
              "id": "item_123",
              "title": "Blue Jeans",
              "price": 5000
            },
            "quantity": 1,
            "totals": [
              {"type": "subtotal", "amount": 5000},
              {"type": "total", "amount": 5000}
            ]
          }
        ],
        "currency": "USD",
        "totals": [
          {
            "type": "subtotal",
            "amount": 5000
          },
          {
            "type": "fulfillment",
            "display_text": "Shipping",
            "amount": 500
          },
          {
            "type": "total",
            "amount": 5500
          }
        ],
        "fulfillment": {
          "methods": [
            {
              "id": "shipping_1",
              "type": "shipping",
              "line_item_ids": ["item_123"],
              "selected_destination_id": "dest_home",
              "destinations": [
                {
                  "id": "dest_home",
                  "street_address": "123 Main St",
                  "address_locality": "Springfield",
                  "address_region": "IL",
                  "postal_code": "62701",
                  "address_country": "US"
                }
              ],
              "groups": [
                {
                  "id": "package_1",
                  "line_item_ids": ["item_123"],
                  "selected_option_id": "standard",
                  "options": [
                    {
                      "id": "standard",
                      "title": "Standard Shipping",
                      "description": "Arrives in 5-7 business days",
                      "totals": [
                        {
                          "type": "total",
                          "amount": 500
                        }
                      ]
                    },
                    {
                      "id": "express",
                      "title": "Express Shipping",
                      "description": "Arrives in 2-3 business days",
                      "totals": [
                        {
                          "type": "total",
                          "amount": 1000
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        "links": [
          {
            "type": "privacy_policy",
            "url": "https://business.example.com/privacy"
          },
          {
            "type": "terms_of_service",
            "url": "https://business.example.com/terms"
          }
        ],
        "continue_url": "https://business.example.com/checkout-sessions/checkout_abc123",
        "expires_at": "2026-01-11T18:30:00Z"
      }
    },
    "content": [
      {
        "type": "text",
        "text": "{\"checkout\":{\"ucp\":{...},\"id\":\"checkout_abc123\",...}}"
      }
    ]
  }
}

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

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

Maps to the Get Checkout operation.

Input Schema¶

id (String): Required. The ID of the checkout session.

Output Schema¶

Checkout object.

`update_checkout`¶

Maps to the Update Checkout operation.

Input Schema¶

id (String): Required. The ID of the checkout session to update.
checkout (Checkout): Required. Contains the updated checkout session data.
- Extensions (Optional):
  - dev.ucp.shopping.buyer_consent: Buyer Consent
  - dev.ucp.shopping.fulfillment: Fulfillment
  - dev.ucp.shopping.discount: Discount
  - dev.ucp.shopping.ap2_mandate: AP2 Mandates

Output Schema¶

Checkout object.

Example¶

RequestResponse

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "update_checkout",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
        }
      },
      "id": "checkout_abc123",
      "checkout": {
        "buyer": {
          "email": "jane.doe@example.com",
          "first_name": "Jane",
          "last_name": "Doe"
        },
        "line_items": [
          {
            "item": {
              "id": "item_123"
            },
            "quantity": 1
          }
        ],
        "currency": "USD",
        "fulfillment": {
          "methods": [
            {
              "id": "shipping_1",
              "line_item_ids": ["item_123"],
              "groups": [
                {
                  "id": "package_1",
                  "selected_option_id": "express"
                }
              ]
            }
          ]
        }
      }
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "structuredContent": {
      "checkout": {
        "ucp": {
          "version": "draft",
          "capabilities": {
            "dev.ucp.shopping.checkout": [
              {"version": "draft"}
            ],
            "dev.ucp.shopping.fulfillment": [
              {"version": "draft"}
            ]
          },
          "payment_handlers": {
            "com.example.vendor.delegate_payment": [
              {"id": "handler_1", "version": "draft", "available_instruments": [{"type": "card"}], "config": {}}
            ]
          }
        },
        "id": "checkout_abc123",
        "status": "incomplete",
        "buyer": {
          "email": "jane.doe@example.com",
          "first_name": "Jane",
          "last_name": "Doe"
        },
        "line_items": [
          {
            "id": "item_123",
            "item": {
              "id": "item_123",
              "title": "Blue Jeans",
              "price": 5000
            },
            "quantity": 1,
            "totals": [
              {"type": "subtotal", "amount": 5000},
              {"type": "total", "amount": 5000}
            ]
          }
        ],
        "currency": "USD",
        "totals": [
          {
            "type": "subtotal",
            "amount": 5000
          },
          {
            "type": "fulfillment",
            "display_text": "Shipping",
            "amount": 1000
          },
          {
            "type": "total",
            "amount": 6000
          }
        ],
        "fulfillment": {
          "methods": [
            {
              "id": "shipping_1",
              "type": "shipping",
              "line_item_ids": ["item_123"],
              "selected_destination_id": "dest_home",
              "destinations": [
                {
                  "id": "dest_home",
                  "street_address": "123 Main St",
                  "address_locality": "Springfield",
                  "address_region": "IL",
                  "postal_code": "62701",
                  "address_country": "US"
                }
              ],
              "groups": [
                {
                  "id": "package_1",
                  "line_item_ids": ["item_123"],
                  "selected_option_id": "express",
                  "options": [
                    {
                      "id": "standard",
                      "title": "Standard Shipping",
                      "description": "Arrives in 5-7 business days",
                      "totals": [
                        {
                          "type": "total",
                          "amount": 500
                        }
                      ]
                    },
                    {
                      "id": "express",
                      "title": "Express Shipping",
                      "description": "Arrives in 2-3 business days",
                      "totals": [
                        {
                          "type": "total",
                          "amount": 1000
                        }
                      ]
                    }
                  ]
                }
              ]
            }
          ]
        },
        "links": [
          {
            "type": "privacy_policy",
            "url": "https://business.example.com/privacy"
          },
          {
            "type": "terms_of_service",
            "url": "https://business.example.com/terms"
          }
        ],
        "continue_url": "https://business.example.com/checkout-sessions/checkout_abc123",
        "expires_at": "2026-01-11T18:30:00Z"
      }
    },
    "content": [
      {
        "type": "text",
        "text": "{\"checkout\":{\"ucp\":{...},\"id\":\"checkout_abc123\",...}}"
      }
    ]
  }
}

`complete_checkout`¶

Maps to the Complete Checkout operation.

Input Schema¶

meta (Object): Required. Request metadata containing:
- ucp-agent (Object): Required. Platform agent identification.
- idempotency-key (String, UUID): Required. Unique key for retry safety.
id (String): Required. The ID of the checkout session.
checkout (Checkout): Required. Contains payment credentials and other finalization data to execute the transaction.

Output Schema¶

Checkout object, containing a partial order that holds only id and permalink_url.

`cancel_checkout`¶

Maps to the Cancel Checkout operation.

Input Schema¶

meta (Object): Required. Request metadata containing:
- ucp-agent (Object): Required. Platform agent identification.
- idempotency-key (String, UUID): Required. Unique key for retry safety.
id (String): Required. The ID of the checkout session.

Output Schema¶

Checkout object with status: canceled.

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 errors like unavailable merchandise) are returned as JSON-RPC result with structuredContent containing the UCP envelope and messages:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "checkout": {
        "ucp": {
          "version": "draft",
          "capabilities": {
            "dev.ucp.shopping.checkout": [{"version": "draft"}]
          }
        },
        "id": "checkout_abc123",
        "status": "incomplete",
        "line_items": [
          {
            "id": "item_456",
            "quantity": 100,
            "available_quantity": 12
          }
        ],
        "messages": [
          {
            "type": "warning",
            "code": "quantity_adjusted",
            "content": "Quantity adjusted, requested 100 units but only 12 available",
            "path": "$.line_items[0].quantity"
          }
        ],
        "continue_url": "https://merchant.com/checkout/checkout_abc123"
      }
    },
    "content": [
      {"type": "text", "text": "{\"checkout\":{\"ucp\":{...},\"id\":\"checkout_abc123\",...}}"}
    ]
  }
}

For create_checkout, when all items unavailable and no checkout can be created, JSON-RPC result with structuredContent containing the UCP envelope and messages:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "ucp": { "version": "2026-01-11", "status": "error" },
      "messages": [
        {
          "type": "error",
          "code": "item_unavailable",
          "content": "Items are not available for purchase in your region",
          "severity": "unrecoverable",
          "path": "$.line_items"
        }
      ],
      "continue_url": "https://merchant.com/"
    },
    "content": [
      {"type": "text", "text": "{\"ucp\":{...},\"messages\":[...]}"}
    ]
  }
}

Message Signing¶

Platforms SHOULD authenticate agents when using MCP transport. When using HTTP Message Signatures, all checkout operations follow the Message Signatures specification.

Request Signing¶

UCP's MCP transport uses streamable HTTP, allowing the same RFC 9421 signature mechanism as REST. The signature is applied at the HTTP layer:

Header	Required	Description
`Signature-Input`	Yes	Describes signed components
`Signature`	Yes	Contains the signature value
`Content-Digest`	Yes	SHA-256 hash of request body
`UCP-Agent`	Yes	Signer identity (profile URL)
`Idempotency-Key`	Cond.*	Unique key for replay protection

* Required for complete_checkout and cancel_checkout

Example Signed Request:

POST /mcp HTTP/1.1
Host: business.example.com
Content-Type: application/json
UCP-Agent: profile="https://platform.example/.well-known/ucp"
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
Content-Digest: sha-256=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
Signature-Input: sig1=("@method" "@authority" "@path" "content-digest" "content-type" "ucp-agent" "idempotency-key");keyid="platform-2026"
Signature: sig1=:MEUCIQDXyK9N3p5Rt...:

{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"complete_checkout","arguments":{"id":"checkout_abc123","checkout":{"payment":{...}}}}}

The Content-Digest binds the JSON-RPC body to the signature. No JSON canonicalization is required.

See Message Signatures - MCP Transport for details.

Response Signing¶

Response signatures are RECOMMENDED for:

complete_checkout responses (order confirmation)

Response signatures are OPTIONAL for:

create_checkout, get_checkout, update_checkout, cancel_checkout

Example Signed Response:

HTTP/1.1 200 OK
Content-Type: application/json
Content-Digest: sha-256=:Y5fK8nLmPqRsT3vWxYzAbCdEfGhIjKlMnO...:
Signature-Input: sig1=("@status" "content-digest" "content-type");keyid="merchant-2026"
Signature: sig1=:MFQCIH7kL9nM2oP5qR8sT1uV4wX6yZaB3cD...:

{"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"..."}],"structuredContent":{"checkout":{"id":"checkout_abc123","status":"completed"}}}}

See Message Signatures - REST Response Signing for the signing algorithm (identical for MCP over HTTP).

Conformance¶

A conforming MCP transport implementation MUST:

Implement JSON-RPC 2.0 protocol correctly.
Provide all core checkout 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.

A conforming implementation SHOULD:

Authenticate agents using one of the supported mechanisms (API keys, OAuth, mTLS, or HTTP Message Signatures per Message Signatures).
Verify authentication on incoming requests before processing.

Implementation¶

UCP operations are defined using OpenRPC (JSON-RPC schema format). The MCP specification requires all tool invocations to use a tools/call method with the operation name and arguments wrapped in params. Implementers MUST apply this transformation:

OpenRPC	MCP
`method`	`params.name`
`params`	`params.arguments`

Param conventions:

meta contains request metadata
id identifies the target resource (path parameter equivalent)
checkout contains the domain payload (body equivalent)

Example: Given the complete_checkout operation defined in OpenRPC:

{
  "method": "complete_checkout",
  "params": {
    "meta": {
      "ucp-agent": { "profile": "https://..." },
      "idempotency-key": "550e8400-e29b-41d4-a716-446655440000"
    },
    "id": "checkout_abc123",
    "checkout": { "payment": {...} }
  }
}

Implementers MUST expose this as an MCP tools/call endpoint:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "complete_checkout",
    "arguments": {
      "meta": {
        "ucp-agent": { "profile": "https://..." },
        "idempotency-key": "550e8400-e29b-41d4-a716-446655440000"
      },
      "id": "checkout_abc123",
      "checkout": { "payment": {...} }
    }
  }
}

Checkout Capability - MCP Binding¶

Protocol Fundamentals¶

Discovery¶

Request Metadata¶

Tools¶

Identifier Pattern¶

create_checkout¶

Input Schema¶

Output Schema¶

Example¶

get_checkout¶

Input Schema¶

Output Schema¶

update_checkout¶

Input Schema¶

Output Schema¶

Example¶

complete_checkout¶

Input Schema¶

Output Schema¶

cancel_checkout¶

Input Schema¶

Output Schema¶

Error Handling¶

Business Outcomes¶

Message Signing¶

Request Signing¶

Response Signing¶

Conformance¶

Implementation¶

`create_checkout`¶

`get_checkout`¶

`update_checkout`¶

`complete_checkout`¶

`cancel_checkout`¶