ucp-checkout-mcp

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 an errors[] array, where each error has code, message, severity, and details fields

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:

1. Implement the 5 tools using your MCP framework (e.g., @modelcontextprotocol/sdk for Node, mcp for Python)
2. Extract _meta.ucp.profile from every tool call for negotiation
3. Return checkout objects as JSON in the MCP tool result
4. Return errors using JSON-RPC error format with UCP data payload
5. Implement idempotency on create and complete tools

Connecting to an existing MCP server (e.g., Shopify):

1. Authenticate (Shopify uses OAuth2 client_credentials for access tokens)
2. Connect to the MCP endpoint
3. Call tools with proper _meta.ucp.profile and checkout payloads
4. 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_token with client credentials
• MCP endpoint is POST https://{shop-domain}/api/ucp/mcp