Transport Failures
A store's manifest can declare MCP, REST, A2A, or an embedded entry for the Embedded Checkout handoff (ECP, used at the payment step, not a way to connect). The Playground connects over MCP and REST; an A2A endpoint is shown as declared and isn't inspected. Separately from UCP, a store page can offer its own WebMCP tools. Each has its own failure modes; knowing which layer failed is the first step.
MCP failures
MCP uses JSON-RPC over HTTP. Failures surface as either JSON-RPC error codes or HTTP-level errors from the endpoint.
The store's MCP server does not recognize the tool name — the store implements a subset of UCP tools, or the name is misspelled in the request.
FixList the store's tools in the Inspector and match names exactly; a missing tool may be served over REST instead.
The request lacked valid credentials.
FixSee Authorization Failures for the OAuth handshake and its failure modes.
The MCP server accepted the call but the tool itself failed during execution — often an unhandled null or a database error in the store's implementation.
FixReproduce the call in the Inspector with the same arguments and review the store's server logs for the failing tool.
The endpoint returned an HTTP error before JSON-RPC processing — expired SSL certificates (502), rate limiting (429), or the endpoint down (503).
FixConfirm with curl outside the harness; transport-level HTTP errors are infrastructure, not protocol.
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found"
}
}REST failures
REST is used for REST-only stores, when you choose UCP · REST in the Agent page's Connection picker, and as a fallback when MCP fails for specific tools.
The REST endpoint path does not exist.
FixCheck that the store publishes REST endpoints and the URL mapping is correct — see REST API Fallback.
The server errored processing the request.
FixReview the store's server logs; the session timeline carries the exact request body that triggered it.
Missing Access-Control-Allow-Origin headers prevent browser-based agents from reaching the endpoint. The Playground calls your endpoints from its own servers, so CORS doesn't affect its runs.
FixAdd CORS headers on the store's endpoint if browser-based agents need to call it.
ECP failures
The Embedded Checkout handoff (ECP) uses iframes with MessagePort for secure payment flows; failures here are browser-level.
The store's X-Frame-Options or Content-Security-Policy headers block embedding.
FixAllow framing from the Playground's domain in Content-Security-Policy: frame-ancestors (or drop the blocking X-Frame-Options).
The iframe loaded but never established a communication channel — usually the checkout page doesn't include the ECP client script.
FixVerify the ECP client script loads on the checkout page and initializes the MessagePort handshake.
The embedded checkout could not produce a payment token (e.g., Stripe or Google Pay token).
FixCheck the payment provider's client-side SDK configuration on the store.
Store page (WebMCP) failures
A store-page run opens the store's page (https:// + the domain you entered) in a browser on our side and reads the tools it registers through document.modelContext. WebMCP is not a UCP transport; these failures are about the page, not your UCP endpoint.
The page loaded, but document.modelContext wasn't there. The store hasn't shipped WebMCP, or only offers it on other pages.
FixRegister your tools on the page the domain opens (usually the home page). Check the Inspector's WEBMCP view: it says whether document.modelContext is present.
document.modelContext exists, but no tools were registered when we read it — often because tools are registered late, only after a click, or only on product or cart pages.
FixRegister your tools as the page loads, without waiting for user interaction.
Shown as "The browser could not open the page: …" with a timeout. Very heavy pages can take too long to load in the browser. A slow load is retried once, and a page that has registered its tools by then is used anyway; the run fails only when the page still has no tools.
FixRegister tools early in page load, and reduce what has to load before they're registered.
Every browser we run is in use. A store-page run waits briefly for one, and the Agent page says so while it waits. The Inspector says "All browsers are still busy. Try again in a minute."
FixTry again shortly. Nothing is wrong with your store.
Also in the Inspector's WEBMCP view: "That address is not a public web page." (the URL isn't a public site) and "The page could not be loaded in the browser." See WebMCP: the store page.
Automatic REST fallback
When an MCP call fails for a specific tool, the Playground automatically falls back to REST for that tool only. The fallback is per-tool, not global — if search_shop_catalog fails over MCP but create_cart succeeds, only search calls switch to REST.
Error code -32603 (internal error) does not trigger REST fallback. It means MCP accepted the call but the tool itself failed — falling back to REST would likely produce the same error. Only transport-level failures like -32601 and HTTP errors trigger the switch.
Debugging steps
- Check the Inspector — raw JSON-RPC requests and responses, with the exact error code and message inline.
- Verify endpoint accessibility — use
curlto confirm the endpoint is reachable and returning valid JSON-RPC. - Check CORS headers — only for browser-based agents: confirm
Access-Control-Allow-Origincarries the correct domain. - Review the session timeline — every tool call in order with timing; find the failing call and whether later calls recovered.
For stores that support REST alongside MCP, see REST API Fallback for configuration details.