Shopify Global Catalog: migrar de REST a MCP/UCP antes del 2 de noviembre

El 2 de noviembre de 2026, Shopify dejará de aceptar tráfico en su Global Catalog REST API. En desuso desde abril, este servicio de descubrimiento de productos de varios comercios dejará de responder en sus antiguos endpoints /global/.... El plazo, anunciado el 9 de octubre de 2026, obliga a migrar las integraciones afectadas a Global Catalog MCP, que sigue el Universal Commerce Protocol (UCP).

Este cambio no significa que Shopify vaya a eliminar todas sus API REST: afecta específicamente a Global Catalog, que se utiliza para buscar productos en varias tiendas Shopify. Para un desarrollador de integraciones de comercio electrónico, SaaS o agentes de compra, la migración exige algo más que cambiar una URL: hay que adaptar el transporte, las herramientas invocadas, los identificadores, el perfil del agente y los esquemas de las respuestas. A continuación, presentamos cuatro conversiones de REST a MCP y un método de validación antes de la interrupción.

¿Qué integraciones de Shopify dejarán de funcionar el 2 de noviembre?

Solo se verán afectados los clientes de la antigua Global Catalog REST API. Se trata del servicio que permitía descubrir y consultar productos de varias tiendas en el dominio discover.shopifyapps.com. Shopify anuncia la interrupción de todas las rutas /global/... correspondientes, incluidos los endpoints de catálogos guardados.

Esto no implica la interrupción de la Admin API ni de la Storefront API, ni una migración obligatoria de todas las tiendas a MCP. Shopify distingue además entre Storefront Catalog MCP y Global Catalog MCP para un agente limitado al catálogo de un único comerciante. Por tanto, empiece por inventariar los dominios y las rutas que utiliza su aplicación: no modifique las integraciones que no estén afectadas.

El mapeo oficial: cuatro endpoints REST a tres herramientas MCP

Shopify publicó este mapeo el 9 de octubre. En MCP no se llaman cuatro rutas HTTP distintas: se envía una solicitud tools/call JSON-RPC a un punto de entrada común y el nombre de la herramienta aparece en params.name. Los argumentos de negocio se agrupan en params.arguments.catalog.

Preparar el cliente: endpoint MCP, perfil UCP y autenticación

El endpoint de destino es https://catalog.shopify.com/api/ucp/mcp. Cada llamada debe incluir params.arguments.meta.ucp-agent.profile, es decir, la URL del perfil UCP de su agente. Este perfil indica las capacidades que declara el agente; el servidor negocia las herramientas y los campos disponibles. Los ejemplos siguientes utilizan el perfil ilustrativo alojado por Shopify, que debe sustituirse por el perfil de su aplicación en producción.

Para exponer las herramientas globales y sus campos enriquecidos, Shopify especifica que un perfil personalizado debe declarar las capacidades básicas dev.ucp.shopping.catalog.search y dev.ucp.shopping.catalog.lookup, así como la extensión dev.shopify.catalog.global. Una extensión sin su capacidad básica no es suficiente.

Se puede conservar la autenticación bearer existente: los tokens creados con las credenciales de cliente del Dev Dashboard siguen siendo válidos. Sin embargo, el cuerpo de la solicitud ya no es un JSON propio del antiguo endpoint REST. El código siguiente ilustra el transporte HTTP a MCP; la configuración real depende del cliente utilizado y de cómo gestione las sesiones MCP.

# Guardar el primer JSON en 01-search-catalog.json
# Usar un token personal/de servidor obtenido a través del Dev Dashboard.
curl -X POST 'https://catalog.shopify.com/api/ucp/mcp' \
  -H 'Authorization: Bearer <SHOPIFY_CATALOG_TOKEN>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data-binary @01-search-catalog.json

Atención: el archivo 01-search-catalog.json debe contener el sobre completo que se muestra en el ejemplo siguiente. No incluya nunca un token real en un archivo público, un navegador o un repositorio de demostración; utilice los secretos de su backend.

Tutorial: migrar cuatro solicitudes REST sin perder su lógica

1. Búsqueda en varios comercios: GET /global/v2/search → search_catalog

Antes: el backend consultaba GET https://discover.shopifyapps.com/global/v2/search con sus parámetros REST de búsqueda. Después: llama a search_catalog con una consulta de texto en catalog.query, el país del comprador en catalog.context.address_country y el límite en catalog.pagination.limit.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 1,
  "params": {
    "name": "search_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "query": "zapatos para correr",
        "context": {
          "address_country": "FR",
          "language": "fr"
        },
        "pagination": {
          "limit": 10
        }
      }
    }
  }
}

La respuesta UCP agrupa productos y sus ofertas de varios comerciantes. Según la búsqueda, los filtros, la información de disponibilidad y los datos enriquecidos pueden modificar el resultado: compruebe la visualización en su lógica de negocio en lugar de dar por sentado que el esquema REST no cambia.

2. Ficha de producto: GET /global/v2/p/{upid} → get_product

Antes: se consultaba una ficha mediante GET https://discover.shopifyapps.com/global/v2/p/{upid}. Después: la herramienta get_product recibe un identificador canónico con el formato gid://shopify/p/{upid} en catalog.id.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 2,
  "params": {
    "name": "get_product",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "id": "gid://shopify/p/7f3a2b8c1d9e",
        "context": {
          "address_country": "FR"
        }
      }
    }
  }
}

La herramienta puede devolver opciones, variantes e indicadores de disponibilidad y ayudar a precisar la selección. Es esencial sustituir la ruta REST por una cadena GID en el lugar adecuado: pasar el identificador antiguo sin más al nuevo formato puede dar un resultado incorrecto o no encontrarlo.

3. Variante: GET /global/v2/p/by-variant/{vid} → get_product

Antes: la consulta por variante utilizaba GET https://discover.shopifyapps.com/global/v2/p/by-variant/{vid}. Después: se llama a la misma herramienta get_product, pero con gid://shopify/ProductVariant/{vid}. Esta distinción es importante para un asistente que parte de una referencia concreta, en lugar de una ficha de producto general.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 3,
  "params": {
    "name": "get_product",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "id": "gid://shopify/ProductVariant/87654321",
        "context": {
          "address_country": "FR"
        }
      }
    }
  }
}

Cuando el agente debe seleccionar un color o una talla, la matriz opcional catalog.selected permite enviar opciones con el formato {"name":"Color","label":"Black"}. Las respuestas de get_product exponen las opciones efectivas y los indicadores available o exists.

4. Consulta por lotes: POST /global/v2/lookup → lookup_catalog

Antes: se podían resolver varias referencias mediante POST https://discover.shopifyapps.com/global/v2/lookup. Después: la lista se pasa en catalog.ids, que debe contener entre 1 y 50 identificadores por llamada. El servicio acepta GID de productos y variantes, así como URL de productos de Shopify compatibles.

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 4,
  "params": {
    "name": "lookup_catalog",
    "arguments": {
      "meta": {
        "ucp-agent": {
          "profile": "https://shopify.dev/ucp/agent-profiles/examples/2026-08-25/valid-with-capabilities.json"
        }
      },
      "catalog": {
        "ids": [
          "gid://shopify/p/7f3a2b8c1d9e",
          "gid://shopify/ProductVariant/87654321"
        ],
        "context": {
          "address_country": "FR"
        }
      }
    }
  }
}

Si su aplicación carga lotes grandes, divídalos en grupos de 50 como máximo. Shopify especifica que los identificadores que remiten al mismo producto pueden agruparse y que los ID no encontrados aparecen, entre otros casos, en forma de mensajes not_found: por tanto, no siempre hay una correspondencia de «una entrada, una línea en la salida».

¿Y si la aplicación utiliza catálogos guardados?

Las antiguas URL REST dedicadas a los catálogos guardados también dejarán de funcionar. Con UCP, hay que pasar el identificador del catálogo configurado en el Dev Dashboard mediante catalog.catalog_id, dentro del mismo objeto catalog. Este identificador se añade a los demás parámetros de negocio, como query; ya no forma parte de la ruta URL.

En una llamada a search_catalog, los filtros del catálogo guardado delimitan la búsqueda. Shopify también especifica que se puede combinar un prefijo de búsqueda guardado con catalog.query. El antiguo alias catalog.saved_catalog_slug está documentado como obsoleto: para una nueva integración, prefiera catalog.catalog_id.

Adaptar los esquemas UCP en el código de la aplicación

La diferencia no se limita a la llamada a la herramienta. Los ejemplos de Shopify devuelven contenido estructurado en result.structuredContent: los productos tienen campos nuevos, un contenedor ucp describe las capacidades y versiones negociadas, y la paginación puede incluir cursor y has_next_page. Los importes, como price_range.min.amount, se expresan en unidades monetarias menores: no los muestre directamente como euros o dólares.

Un adaptador entre el cliente MCP y la aplicación reduce el riesgo de acoplar todo el front-end al esquema de transporte. Este pequeño ejemplo de JavaScript presupone que un cliente MCP ya ha decodificado la respuesta JSON-RPC y no sustituye la validación completa de los datos de negocio:

// Respuesta JSON-RPC ya decodificada por el cliente MCP
function normalizeCatalogResponse(rpcResponse) {
  if (rpcResponse.error) {
    throw new Error(rpcResponse.error.message || "Error MCP");
  }

  const data = rpcResponse.result?.structuredContent;
  if (!data) {
    throw new Error("Falta la respuesta UCP estructurada");
  }

  return {
    products: Array.isArray(data.products) ? data.products : [],
    messages: Array.isArray(data.messages) ? data.messages : [],
    pagination: data.pagination ?? null,
  };
}

// data.products[i].price_range.min.amount: importe en unidades menores
// data.messages puede incluir el código "not_found" para un ID desconocido

Otra particularidad importante para un comparador: Shopify marca algunos atributos del catálogo como Inferred (descripciones enriquecidas, opciones normalizadas, características inferidas). Pueden ser incompletos o aproximados. No los presente automáticamente como afirmaciones originales del comerciante. Para los precios, las variantes, los enlaces de checkout y la disponibilidad, compruebe los esquemas y las reglas de negocio antes de ponerlo en producción.

Probar la migración antes de la interrupción

Shopify ofrece el AI Toolkit y la CLI UCP para probar las herramientas sin empezar por integrar un cliente propio completo. Los siguientes comandos reproducen la sintaxis documentada, con valores de ejemplo y un país de comprador francés:

# Prueba de búsqueda, según los ejemplos de la CLI UCP de Shopify
ucp catalog search \
  --set /query='zapatos para correr' \
  --set /context/address_country=FR \
  --view :compact --format md

# Prueba de resolución de una variante conocida
ucp catalog lookup \
  --set '/ids/0=gid://shopify/ProductVariant/87654321'

Para asegurar el cambio, prepare un pequeño conjunto de pruebas con una consulta de texto, una ficha de producto existente, una variante existente, una variante desconocida, un lote de más de 50 ID que haya que dividir y una búsqueda limitada a un catálogo guardado. Compare los resultados con el comportamiento de negocio esperado: campos ausentes, agrupaciones, paginación, precios y localización. Supervise la frecuencia de los errores not_found, los tiempos de respuesta y las restricciones de las políticas UCP.

De REST a MCP: un precedente interesante, no el fin de las API tradicionales

La lección va más allá de Shopify. En un flujo de trabajo en el que un agente elige dinámicamente una herramienta para descubrir productos, una interfaz MCP acompañada de esquemas UCP y una negociación de capacidades puede simplificar la interoperabilidad entre proveedores y asistentes. El servidor expone operaciones de negocio con nombre en lugar de una serie de URL especializadas; el agente puede elegir search_catalog y luego get_product según su objetivo.

Pero MCP no sustituye sistemáticamente a REST. Las API web tradicionales y los esquemas GraphQL siguen siendo adecuados para otras aplicaciones: interfaces predecibles, sincronización de datos, operaciones administrativas o integración entre tiendas. En este caso, Shopify moderniza un caso concreto de descubrimiento multi-comercio orientado a agentes. El verdadero criterio de arquitectura es la necesidad de interoperabilidad entre agentes y herramientas, no la idea de que un protocolo sea intrínsecamente superior en todos los escenarios.

Para un SaaS o un asistente de comercio electrónico, la decisión práctica es sencilla: migrar ahora las llamadas de Global Catalog REST, aislar la nueva dependencia detrás de un adaptador de datos, mantener una batería de pruebas de negocio y generalizar MCP solo allí donde la naturaleza del flujo de trabajo lo justifique.