orcaqubits/agentic-commerce-skills-plugins/acp-checkout-mcp

ACP Checkout — MCP Binding

Before writing code

Fetch live docs:

1. Fetch https://github.com/agentic-commerce-protocol/agentic-commerce-protocol/releases for the current spec version.
2. Fetch the official OpenRPC document — spec/<version>/openrpc/openrpc.agentic_checkout.json in the repo. Since the 2026-04-17 release there is a machine-readable JSON-RPC description of the checkout binding; use it rather than hand-deriving tool names. The table below predates it.
3. Fetch https://developers.openai.com/commerce/specs/checkout/ for checkout operation semantics.
4. Fetch https://modelcontextprotocol.io/specification/ — it redirects to the current MCP revision. Confirm the transport model before writing server code; MCP's core changed shape between revisions (the stateless core removed the initialize handshake and Mcp-Session-Id), so a server written against an older revision will not match a current client.
5. Fetch MCP SDK docs: web-search site:github.com modelcontextprotocol python-sdk or typescript-sdk for the current SDK.

Conceptual Architecture

What MCP Binding Means

ACP's REST checkout operations can be exposed as MCP tools via an MCP server. This allows AI agents that use tool-calling (Claude, ChatGPT, Gemini) to invoke checkout operations directly as tools rather than making raw HTTP calls.

Since 2026-04-17 this mapping is specified, not improvised — the OpenRPC document is the source of truth for method names and parameter shapes. Treat the mapping below as orientation and the OpenRPC document as normative.

Mapping REST to MCP Tools

Each REST checkout operation becomes an MCP tool:

Tool Input Schemas

Each MCP tool accepts JSON input matching the corresponding REST request body. The tool's inputSchema should be derived from the ACP OpenAPI spec's request schemas.

Tool Output

Each tool returns the CheckoutSession object (or error) as JSON, matching the REST response body.

MCP Server Architecture

AI Agent (Claude/ChatGPT)
    ↓ tool call (JSON-RPC)
MCP Server (your code)
    ↓ business logic
Checkout Service (same logic as REST)
    ↓ payment
PSP (Stripe)

The MCP server wraps the same business logic that the REST endpoints use. The checkout service layer should be shared between REST and MCP bindings.

Key Considerations

• Idempotency — MCP doesn't have HTTP headers, so pass idempotency_key as a tool parameter
• API versioning — Include api_version as a tool parameter or server configuration
• Authentication — MCP transport handles auth (stdio for local, SSE/streamable-HTTP for remote)
• Error handling — Return ACP error objects as tool errors with the same type/code/message structure
• Statelessness — Each tool call should be stateless; session state lives in the CheckoutSession object

Use Cases

• AI agents that prefer tool-calling over raw HTTP
• Claude Desktop / Claude Code integrations
• Multi-agent architectures where commerce is one capability
• Rapid prototyping without building a full REST server

Best Practices

• Share the checkout business logic layer between REST and MCP bindings
• Derive tool input schemas from the ACP OpenAPI spec (don't hand-write them)
• Include descriptive tool descriptions so the agent understands when to use each tool
• Test with the MCP Inspector before connecting to an agent

Fetch the latest ACP OpenAPI spec and MCP SDK documentation for exact schemas and server setup before implementing.