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, per the official Shopify developer changelog. The old /api/mcp endpoint and the previous search_shop_catalog 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, two tool renames, and a response-schema check against the new UCP catalog spec. 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. The Hydrogen Winter 26 release made every Hydrogen storefront on Oxygen an MCP-ready endpoint by default, and the Storefront API proxy that exposes the new /api/ucp/mcp path is now expected to be in place. Sequencing matters — UCP assumes the proxy is already wrapping your storefront routes.

The 90-Second Engineering Action List

What changed, in six lines

• Endpoint: /api/mcp deprecated; new endpoint /api/ucp/mcp.
• Hard sunset: June 15, 2026 — after that, the legacy endpoint and the previous tool names stop responding.
• Tool renames: the previous search_shop_catalog maps to search_catalog; the previous lookup tool maps to lookup_catalog; get_product is the new full-product retrieval tool with interactive variant selection and availability signals.
• Request and response shapes: updated to match the UCP catalog spec — re-run your client-side schema validation against the published UCP catalog reference.
• Hydrogen Winter 26: Storefront MCP is supported on every Hydrogen storefront on Oxygen out of the box. UCP assumes the Storefront API proxy is in place.
• Action sequence: grep /api/mcp in your codebase, rename the endpoint, rename the tool calls, validate the response shape against the UCP spec, run a parallel test suite, ship before June 15.

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 name: "search_shop_catalog" instead of name: "search_catalog". The renames are deterministic — Shopify's changelog is explicit that the previous search and lookup tools are deprecated in favour of search_catalog, lookup_catalog, and get_product, and that the request and response shapes are updated to match UCP.

The third is the response shape itself. UCP is a layered protocol with capability declarations alongside the commerce payload. The shape of a get_product response now follows the UCP catalog specification — pricing, availability, options, and variant data have moved to UCP-aligned fields. Treat the Storefront Catalog MCP documentation as the authoritative reference for the new schemas; client code that hard-coded the legacy field paths 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 at NRF 2026. The Shopify engineering team describes it as a layered design that separates commerce surface area into three concerns: 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 loyalty-vendor extension active, your agent can negotiate reward redemption. If it does not, you get the core checkout schema and your agent should gracefully degrade. UCP uses reverse-domain naming (dev.ucp.shopping.* for the official spec, com.merchantvendor.* for vendor extensions), which 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 merchant-declared capabilities. 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 Winter 26 and the Storefront API Proxy

Per the Hydrogen Winter 26 update, every Hydrogen storefront on Oxygen now supports Storefront MCP, with custom AI agents able to give customers personalised recommendations, manage carts, and walk buyers through checkout — all powered by real-time data through the Storefront API. UCP runs on the same proxy layer that exposes the storefront to AI agents.

For teams already on the latest Hydrogen release, 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 on older Hydrogen releases, 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.

Hydrogen Winter 26 also exposes the Dev MCP server for AI coding tools like Cursor and Claude, giving them access to comprehensive Hydrogen documentation, Storefront API references, and the Hydrogen Cookbook. We have found that pulling the Dev MCP into your IDE during the UCP migration significantly reduces the time spent looking up new schema field paths. If your team is sequencing the broader changes alongside UCP, the order is: confirm the Storefront API proxy is wrapping your routes, audit consent-mode handling on that proxy layer, then ship the UCP endpoint and tool rename. 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.

• 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.
• Rename tool calls. Wherever your agent invokes search_shop_catalog, swap to search_catalog. Wherever it invokes the previous lookup tool, swap to lookup_catalog. get_product is the new full-product retrieval tool — expect the UCP-aligned response shape rather than the legacy Storefront MCP fields.
• Update request shapes against the UCP spec. The core argument keys (query, context) carry over conceptually, but Shopify's changelog explicitly states that the request schemas are updated to match UCP. Treat the Storefront Catalog MCP documentation as the authoritative reference for the new request shape and validate against it before shipping.
• Verify response field locations. The legacy Storefront MCP returned a flat structure with product_name, price, variant_id, and image_url at the top level. Under UCP the product, pricing, availability, and option data follow the UCP catalog spec, which structures them differently. Re-run your client-side schema validation rather than assuming the legacy field paths still resolve.
• Run integration tests in parallel. Keep one suite hitting /api/mcp and a duplicate hitting /api/ucp/mcp. Both should pass during the transition window, then drop the legacy suite once the new endpoint is canonical in production and the old endpoint is no longer in use.
• 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

When to use each pattern

Three commerce-data access patterns now coexist on a Hydrogen storefront. Use this matrix to pick the right one for the job.

Requirement	UCP via /api/ucp/mcp	Direct Storefront API	Custom MCP server
Latency	Medium (proxy + UCP wrap)	Low (direct GraphQL)	Medium-high
Auth	Storefront access token	Storefront/Admin token	Custom (your stack)
Schema versioning	Capability-negotiated	Storefront API version	You own it
AI agent compatibility	Native (MCP binding)	Requires wrapper	Native
Best for	Public agentic search and cart	Frontend rendering	Bespoke enterprise tools

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:

• 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.
• 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.
• 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.
• Validate response shapes. Map every property your client code reads from MCP responses to its UCP equivalent. Treat the Storefront Catalog MCP documentation as the authoritative schema reference rather than relying on the legacy Storefront MCP field paths.
• Plan the canary cutover. Aim to land the new endpoint in production with at least two weeks of parallel running, and complete the cutover well ahead of the June 15 sunset rather than racing it.

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.