Protocols
Firmly’s underlying API is the same regardless of who’s calling it — but how an AI surface communicates with Firmly varies by ecosystem. Different AI platforms have adopted different open standards for agent-driven commerce, and Firmly speaks all of them. This page covers what Firmly supports and how to pick.
The protocols Firmly supports
| Protocol | Owner / Spec | Best for |
|---|---|---|
| UCP — Universal Commerce Protocol | Google (open standard) | AI search surfaces that adopted UCP |
| MCP — Model Context Protocol | Anthropic (open standard) | Any agent built on the MCP standard; works with any LLM or agent framework |
| ACP — Agentic Commerce Protocol | OpenAI (separate spec) | OpenAI commerce surfaces |
| Direct REST | — | Custom agents / backend integrations / when no protocol bridge fits |
All of them ultimately call the same Firmly cart + checkout APIs underneath — what differs is session management, transport, and who controls the checkout UI.
Picking a protocol
| Your agent runs on… | Use |
|---|---|
| An AI search surface using UCP | UCP |
| Any agent built on the Model Context Protocol standard | MCP |
| An OpenAI commerce surface | ACP |
| A custom backend or runtime | Direct REST API |
If you’re building a custom agent and want maximum control, use the Direct REST API path documented in API Reference. If you’re integrating into an existing AI platform, use the platform’s protocol.
Protocol comparison
| Aspect | UCP | MCP |
|---|---|---|
| Spec owner | Google (open) | Anthropic (open) |
| Session model | Multi-step checkout session | Tool-use calls |
| Checkout UI | Surface-native | Agent-controlled; widget for MCP-Apps-compatible hosts |
| Transport | HTTPS REST | SSE / HTTP (MCP-Apps hosts) |
| Discovery layer | Surface’s own product index | Firmly’s discovery tools |
What’s shared across all protocols
The protocol layer is a translation layer — it converts platform-specific requests into Firmly’s cart and checkout operations. Underneath, Firmly does the same things regardless of which protocol called it:
- Cart orchestration
- Payment processing
- Tax + shipping orchestration (using the merchant’s rules)
- Order placement to the merchant’s platform
- Affiliate attribution
This is why a merchant onboarded on Firmly is automatically reachable through every supported protocol without any per-protocol work on the merchant side.
How protocols map to the purchase flow
| Phase | UCP | MCP |
|---|---|---|
| Discovery | The surface’s own product index | Firmly discovery tools |
| Cart creation | UCP session API | MCP cart tools |
| Shipping & promo | UCP session updates | MCP shipping + promo tools |
| Payment + order | UCP complete-session | MCP payment tool |
The architectural insight
UCP and ACP-style surfaces handle discovery on their own platforms (their product indices). MCP relies on Firmly’s discovery tools because it’s a general-purpose agent protocol without a built-in product index.
For checkout, all protocols ultimately call the same Firmly cart and payment APIs. The protocol wrapper translates the request format; the underlying cart orchestration and order placement logic is shared.
Implications for your build
If you’re choosing between protocols, three questions matter most:
- Does my agent ALREADY use one of these protocols? If yes, use it. The platform-native path is always cheaper than going custom.
- Do I need to control the checkout UI? UCP gives Google’s surface control of UI; MCP gives your agent control; Direct REST gives you full UI control.
- What’s my discovery story? UCP and ACP-style surfaces use their own product index; MCP uses Firmly’s discovery tools; Direct REST is whatever you build.
UCP — deep-dive
UCP has the deepest Firmly integration of the three protocols. See the UCP sub-pages for:
- UCP overview — what UCP is and why Firmly implements it
- Checkout flow — the three-step session lifecycle
- Implementation — service architecture, API mapping, well-known manifest
- Security — request authentication, signature verification, rate limiting
- Merchant onboarding — Google Merchant Center setup
- Roadmap — phased implementation status
- Firmly Card handler — proposed encrypted card handler
Related
- How Firmly works — the platform under all protocols
- Cart lifecycle — the state machine your protocol calls drive
- Agentic Commerce overview — solution-level guidance for agent integrations
- Integration patterns — Hosted vs Embedded vs Headless (independent of protocol)