ACP Checkout — MCP Binding
Before writing code
Fetch live docs:
- Web-search
acp agentic commerce protocol MCP server implementationfor MCP binding guidance - Fetch
https://developers.openai.com/commerce/specs/checkout/for checkout operation semantics - Web-search
site:github.com agentic-commerce-protocol MCPfor any official MCP examples - Fetch MCP SDK docs: web-search
site:github.com modelcontextprotocol python-sdkortypescript-sdkfor 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.
Mapping REST to MCP Tools
Each REST checkout operation becomes an MCP tool:
| REST Operation | MCP Tool Name | Description |
|---|---|---|
| POST /checkout_sessions | create_checkout_session | Create a new checkout session with items |
| POST /checkout_sessions/{id} | update_checkout_session | Update session (items, address, fulfillment) |
| GET /checkout_sessions/{id} | get_checkout_session | Retrieve current session state |
| POST /checkout_sessions/{id}/complete | complete_checkout_session | Submit payment to finalize |
| POST /checkout_sessions/{id}/cancel | cancel_checkout_session | Cancel the session |
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_keyas a tool parameter - API versioning — Include
api_versionas 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/messagestructure - 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.