Checkout MCP Binding

Overview

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:

{
  "ucp": {
    "services": {
      "dev.ucp.shopping": {
        "mcp": {
          "schema": "https://ucp.dev/services/shopping/mcp.openrpc.json",
          "endpoint": "https://business.example.com/ucp/mcp"
        }
      }
    }
  }
}

Platform Profile Advertisement

MCP clients MUST include the UCP platform profile URI with every request in the _meta.ucp structure:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "create_checkout",
  "params": {
    "_meta": {
      "ucp": {
        "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
      }
    }
  }
}

Tools

UCP Capabilities map 1:1 to MCP Tools.

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

Example: Create Checkout

Request:

{
  "jsonrpc": "2.0",
  "method": "create_checkout",
  "params": {
    "_meta": {
      "ucp": {
        "profile": "https://platform.example/profiles/v2026-01/shopping-agent.json"
      }
    },
    "buyer": {
      "email": "[email protected]"
    },
    "line_items": [
      {
        "item": {"id": "item_123"},
        "quantity": 1
      }
    ],
    "currency": "USD"
  },
  "id": 1
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ucp": {
      "version": "2026-01-11",
      "capabilities": [...]
    },
    "id": "checkout_abc123",
    "status": "incomplete",
    "line_items": [...],
    "totals": [...],
    "payment": {...}
  }
}

Example: Complete Checkout

Request:

{
  "jsonrpc": "2.0",
  "method": "complete_checkout",
  "params": {
    "_meta": {
      "ucp": {
        "profile": "https://platform.example/profile"
      }
    },
    "id": "checkout_abc123",
    "payment_data": {
      "id": "instr_1",
      "handler_id": "gpay",
      "type": "card",
      "credential": {
        "type": "PAYMENT_GATEWAY",
        "token": "examplePaymentMethodToken"
      }
    },
    "idempotency_key": "550e8400-e29b-41d4-a716-446655440000"
  },
  "id": 2
}

Error Handling

Error responses follow JSON-RPC 2.0 format with UCP error structure in the data field:

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": {
      "status": "error",
      "errors": [
        {
          "code": "MERCHANDISE_NOT_AVAILABLE",
          "message": "One or more cart items are not available",
          "severity": "requires_buyer_input"
        }
      ]
    }
  }
}

Conformance

A conforming MCP transport implementation MUST:

Implement JSON-RPC 2.0 protocol correctly
Provide all core checkout tools
Handle errors with UCP-specific error codes
Validate tool inputs against UCP schemas
Support HTTP transport with streaming