UCP Checkout — MCP Binding
Before writing code
Fetch live spec: Web-search site:ucp.dev specification checkout-mcp and fetch the page for exact tool definitions, JSON-RPC envelope format, and _meta requirements.
For Shopify's production MCP server, fetch https://shopify.dev/docs/agents/checkout/mcp for auth flow and endpoint details.
Conceptual Architecture
How MCP Maps to UCP
UCP over MCP is a 1:1 mapping of checkout operations to MCP tools using JSON-RPC 2.0. The same data model as REST, different envelope.
Five MCP Tools
| MCP Tool Name | Maps To | Key Inputs |
|---|---|---|
create_checkout | POST /checkout-sessions | checkout object + idempotency_key |
get_checkout | GET /checkout-sessions/{id} | id |
update_checkout | PUT /checkout-sessions/{id} | id + checkout object |
complete_checkout | POST .../complete | id + payment_data + idempotency_key |
cancel_checkout | POST .../cancel | id + idempotency_key |
Meta Requirements
Every MCP tool call MUST include _meta.ucp.profile pointing to the platform's UCP profile URI. This replaces the UCP-Agent HTTP header from the REST binding.
Error Mapping
UCP errors embed inside JSON-RPC 2.0 error responses:
- JSON-RPC
error.code:-32603(Internal Error) - JSON-RPC
error.data: Contains anerrors[]array, where each error hascode,message,severity, anddetailsfields
When to Use MCP Binding
- You're building a merchant MCP server that AI agents (Claude, Gemini, etc.) call via tool use
- You're integrating with an existing MCP server (e.g., Shopify's)
- You want AI agents to autonomously browse and purchase without REST client code
Implementation Guidance
Building a Business MCP Server:
- Implement the 5 tools using your MCP framework (e.g.,
@modelcontextprotocol/sdkfor Node,mcpfor Python) - Extract
_meta.ucp.profilefrom every tool call for negotiation - Return checkout objects as JSON in the MCP tool result
- Return errors using JSON-RPC error format with UCP data payload
- Implement idempotency on create and complete tools
Connecting to an existing MCP server (e.g., Shopify):
- Authenticate (Shopify uses OAuth2 client_credentials for access tokens)
- Connect to the MCP endpoint
- Call tools with proper
_meta.ucp.profileand checkout payloads - Parse tool results for checkout status and messages
Shopify MCP Integration
Shopify provides a production MCP server for UCP checkout. Before implementing:
- Fetch https://shopify.dev/docs/agents/checkout/mcp for the latest auth flow, endpoint URL format, and error codes
- Authentication uses
POST https://api.shopify.com/auth/access_tokenwith client credentials - MCP endpoint is
POST https://{shop-domain}/api/ucp/mcp