Hydrogen MCP → UCP Migration: Production Cutover Before June 15

Shopify flipped the Storefront Catalog MCP server to the Universal Commerce Protocol on April 22, 2026. The old /api/mcp endpoint and the previous search_* and lookup_* tool names are deprecated. Both stay live until June 15, 2026 — then they go away. Any Hydrogen storefront, custom AI agent, or third-party integration that still calls the old endpoint after the sunset will fail.

In our experience, this is one of those changes that reads as a footnote on the changelog and lands as a production incident two weeks before the deadline. The work itself is small: an endpoint rename, three tool renames, and a response-schema check. The risk is that it is easy to defer until something visible breaks. For Shopify Plus engineering teams running Hydrogen, this is also not the only change in motion. Hydrogen 2026.4.0 made the Storefront API proxy mandatory by removing the proxyStandardRoutes flag from createRequestHandler, and backend consent mode replaced the legacy _tracking_consent cookie. UCP assumes both of those changes are already in place — sequence matters.

The 90-Second Engineering Action List

What the Rename Actually Breaks

In our experience, three things tend to break in a half-finished UCP migration. The first is the endpoint. The line is short and easy to find, but easy to miss in a team where MCP calls live in two or three different services — replace https://{storeDomain}/api/mcp with https://{storeDomain}/api/ucp/mcp wherever it appears.

The second is the tool names. We have seen merchants update the endpoint, deploy, and then stare at JSON-RPC errors for an hour because their agent still sends tool: "search" instead of tool: "search_catalog". The renames are deterministic — the old search_* tool maps to search_catalog, the old lookup_* tool maps to lookup_catalog, and get_product keeps its name but its response payload now lives under result.product alongside a sibling result.ucp object.

The third is the response shape itself. UCP responses are structured around capability declarations, not just commerce data. A get_product response now returns a top-level ucp block with version and capabilities, alongside the product payload. Pricing has moved into a price_range.min and price_range.max shape — not a single price field — and availability.available is a boolean on both the product and variant level. Code that does product.price or treats availability as a string will silently produce wrong data, not a hard error, which is the worst kind of regression.

UCP Capability Negotiation Explained

The reason this migration looks small in the changelog and matters more than that in practice is that UCP is not an evolution of MCP — it is a layered protocol with a different mental model. UCP is the Universal Commerce Protocol, co-developed by Shopify and Google and published openly. It separates commerce surface area into three layers: a shopping service layer that defines core primitives (checkout sessions, line items, totals), capabilities that group functional areas (Catalog, Checkout, Orders) each independently versioned, and extensions that augment capabilities with domain-specific schemas via composition.

What this means for engineering teams is that the response payload now tells you what the merchant supports. If a merchant has a com.loyaltyprovider.points extension active, your agent can negotiate reward redemption. If it does not, you get the core checkout schema and your agent should gracefully degrade. Reverse-domain naming (dev.ucp.shopping.* for the official spec, com.merchantvendor.* for vendor extensions) means there is no central registry — capabilities can be added by merchants, payment providers, or loyalty vendors without waiting for protocol committees.

The architectural shift this implies for client code: your agent should stop assuming a fixed product schema and start branching on the ucp.capabilities array. We have found this is the single most common source of latent bugs after the rename — code that worked because the old MCP returned exactly one schema now silently misses fields when capabilities are negotiated differently per merchant. For deeper context on how UCP relates to ACP and the older MCP-only patterns, see our breakdown of agentic commerce protocols.

Hydrogen 2026.4.0 and the Mandatory Storefront API Proxy

Hydrogen 2026.4.0, released April 2026, removed the proxyStandardRoutes flag from createRequestHandler. The Storefront API proxy is now always enabled, which means every Hydrogen storefront is an MCP/UCP endpoint by default at /api/mcp (legacy) or /api/ucp/mcp (UCP) — no opt-in required, no flag to set.

For teams already on 2026.4.0, this is a non-event for UCP — the proxy layer is in place and the only work is the endpoint and tool rename. For teams still on 2026.3.x or earlier, there is an extra migration to sequence. The proxy migration must happen first because UCP assumes the proxy is wrapping all storefront routes; without it, the new /api/ucp/mcp endpoint will not be exposed correctly.

The same release also moved consent mode from the legacy _tracking_consent cookie to backend signals carried through the proxy layer. We have seen teams discover this only after a privacy audit flags consent state desync — the old cookie reads stale, the new backend state is authoritative, and code that branches on cookie presence silently breaks. If your team is sequencing all three changes, the order is: proxy migration, then consent mode update, then UCP rename. Doing them out of order leaves you with a working store and broken telemetry, which is hard to detect and harder to debug. For broader Hydrogen production context, see our Hydrogen 2.0 production-readiness guide.

Step-by-Step Migration Diff

We typically execute UCP migrations as a six-step sequence. The work is small, but auditable steps make rollback cheap.

1. Update the endpoint constant. Replace the literal /api/mcp path with /api/ucp/mcp wherever your code constructs the MCP URL. Include environment variables, deployment manifests, and any shared SDK constants in the search.
2. Rename tool calls. Wherever your agent invokes the previous search tool, swap to search_catalog. Wherever it invokes lookup, swap to lookup_catalog. get_product keeps its name but expect the new response shape.
3. Update request shapes. The argument keys (query, context) are stable, but UCP requires a meta.ucp-agent.profile field declaring your agent profile URL. Without it, the merchant cannot negotiate which capabilities to expose to your agent.
4. Verify response field locations. The product payload still lives under result.product, but pricing now lives under product.price_range.min and product.price_range.max instead of a single product.price. Check availability.available as a boolean, not a string.
5. Run integration tests in parallel. Keep one suite hitting /api/mcp and a duplicate hitting /api/ucp/mcp. Both should pass until May 30, then drop the legacy suite once the new endpoint is canonical in production.
6. Ship before June 15. Aim for at least 14 days of canary traffic in production before the sunset, so any latent regression has time to surface under realistic load.

Decision Framework: UCP, Direct Storefront API, or Custom MCP

In our experience, the right default for AI-agent-facing surface area is UCP via the Hydrogen proxy. Direct Storefront API calls remain the right choice for your own frontend rendering — there is no reason to pay the UCP wrapping overhead for code you control. Custom MCP servers make sense only when you have bespoke commerce capabilities (custom B2B pricing tiers, ERP-driven inventory rules) that the standard UCP catalog capability cannot model, and even then, we recommend implementing them as UCP extensions under your own reverse-domain namespace rather than as a parallel protocol. The architectural patterns for scaling a custom MCP layer in production are covered separately in our scaling patterns post.

Testing the Cutover Before June 15

The migration is only as safe as the test suite that verifies it. We typically build a parallel suite that hits both endpoints with the same set of fixtures, asserts the response shapes, and gates the legacy suite removal on a clean canary in production.

The first pattern is fixture parity. Capture a set of representative agent requests from production logs, replay them against both /api/mcp and /api/ucp/mcp, and diff the response shapes. The legacy endpoint should still match the old schema; the UCP endpoint should match the new one. Any drift is a sign that your client code is making assumptions that one or the other endpoint does not satisfy.

The second is canary traffic gating. We have found that 1% of agent traffic to the new endpoint for 48 hours is enough to surface most schema-coupling bugs. If you do not have feature-flag infrastructure for agent traffic, a header-based router ahead of the storefront works — branch on a custom header like X-UCP-Migration: enabled for internal testing accounts before cutting over the full agent population.

The third is the sunset rehearsal. Before June 15, point your test suite at a Pilot or staging storefront where the legacy endpoint is already disabled. This forces every code path that quietly depends on the old endpoint to fail loudly, in test, where you can fix it. Sunset rehearsals are how you catch the half-migrated dependency that nobody remembered was still on the old tool name. For teams already running Shopify Functions in production, the same fixture-from-production pattern applies — the broader testing strategy is covered in our post on Shopify Functions in production.

What to do next

If you run a Hydrogen storefront with any custom AI agent integration, the migration is on a fixed clock. We recommend the following sequence over the next 30 days:

1. Audit your codebase. Run grep -r "/api/mcp" across every service that talks to your Hydrogen storefront — including custom agents, Slack integrations, ERP middleware, and any internal tooling. The endpoint is also commonly referenced in environment variables, so include .env, wrangler.toml, and any deployment manifests.
2. Confirm your Hydrogen version. If you are on 2026.3.x or earlier, schedule the proxy and consent-mode migration first. UCP will not work cleanly without the proxy in place, and consent state desync is a quiet failure mode that is expensive to debug after the fact.
3. Update the endpoint and tool names. The two-line fix is as small as it reads. Keep the legacy endpoint operational in your codebase until the parallel test suite is green.
4. Validate response shapes. Map every property your client code reads from MCP responses to its UCP equivalent. Pay particular attention to price_range, availability.available, and the new top-level ucp capabilities block.
5. Plan the canary cutover. Aim for May 30 in production with the new endpoint, two weeks of parallel running, and full cutover by June 13 — ahead of the June 15 sunset.

For most teams, this is a one-day engineering exercise. The hard part is not the rename — it is making sure the migration is sequenced correctly with the proxy and consent changes that landed alongside it. If your storefront is on Hydrogen and you have not yet looked at this, the cost of acting now is much lower than the cost of acting on June 14.

For broader headless context, see our Catalyst vs Hydrogen comparison and our breakdown of Shopify's four native MCP servers. If you are running a Shopify Plus migration alongside the UCP cutover, our Shopify Plus migration service covers the architecture and risk-register work that keeps both threads from colliding mid-cutover.