A Shopify lançou o Shop MCP em 13 de outubro, oferecendo aos desenvolvedores uma conexão hospedada para busca de produtos, carrinhos e checkout. O serviço está em https://mcp.shop.com/. Suas 17 ferramentas podem encontrar produtos no Shopify Catalog e abrir o checkout com a loja que vende um item. A busca no catálogo não exige chave de API. Uma compra real ainda precisa ser aprovada pelo comprador.

Este guia é para desenvolvedores que configuram um assistente compatível com MCP. As etapas abaixo seguem a documentação da Shopify, conferida em 14 de outubro. A BIG CHANGE não conectou um agente, criou um carrinho nem fez uma compra. Portanto, o guia descreve resultados esperados, não desempenho observado.

A principal mudança

  • O que mudou: A Shopify agora oferece uma conexão MCP hospedada que vai da busca no catálogo ao carrinho da loja e ao checkout. Também documenta a conclusão com Shop Pay para um comprador conectado após confirmação explícita.
  • Quem pode usar: Desenvolvedores com um cliente MCP compatível com a versão do protocolo 2026-07-28, ou código que faça as chamadas HTTP documentadas. Um cliente antigo que usa apenas o handshake initialize não consegue se conectar diretamente.
  • O que verificar: Um checkout é uma transação com uma única loja. completed junto com um order confirma a compra; um carrinho, um link de checkout ou um pagamento em andamento não confirmam.

Antes de conectar

Você precisa de um cliente MCP compatível com servidores HTTP remotos e do método de conexão documentado pela Shopify ou de um aplicativo que chame o servidor por HTTP. Use a URL raiz https://mcp.shop.com/; acrescentar /mcp resulta em 404. As ferramentas de busca e carrinho funcionam sem uma conta Shop. Ao entrar, o assistente pode usar preferências e endereços salvos, encontrar pedidos e oferecer Shop Pay quando a loja der suporte. Para um assistente com código HTTP próprio, a Shopify documenta um fluxo OAuth para dispositivo que o comprador aprova no site do Shop.

Escolha uma consulta de produto, o país de destino e a moeda antes de pesquisar. Separe os requisitos expressos pelo comprador do contexto da busca: país ou moeda ajudam a localizar resultados; limite de preço, tamanho ou destino de entrega são filtros. A API usa unidades menores da moeda para os preços. Seu aplicativo deve ler o campo messages da resposta antes de afirmar que um resultado atende a um filtro, pois o serviço pode informar que o filtro não foi aplicado como solicitado. O guia de busca da Shopify explica a diferença e o limite de 1 a 50 resultados por página.

Um caminho documentado da busca ao pedido

  1. Conecte e confira a busca. Configure o cliente com https://mcp.shop.com/ e carregue o Shop skill da Shopify, se o cliente puder usá-lo. A Shopify sugere testar a conexão pedindo três luminárias de mesa sem criar um carrinho. Uma busca funcional retorna produtos com vendedor, preço em uma moeda indicada e link da loja. Desenvolvedores que usam HTTP podem seguir o início rápido JSON-RPC da Shopify, que inclui os cabeçalhos de protocolo obrigatórios e a solicitação search_catalog. Essa verificação é somente leitura e não exige login.
  2. Escolha o item exato. Execute search_catalog com a consulta e os requisitos do comprador. A busca retorna uma variante em destaque; use get_product se o comprador quiser outro tamanho ou cor. Compare product.selected e o variant.options retornado com cada tamanho, cor e outra escolha especificada pelo comprador antes de mostrar ou comprar. A Shopify diz que a seleção pode ser flexibilizada sem aviso. Quando o comprador escolher um produto ou mudar uma opção, chame get_product novamente para conferir disponibilidade e preço atuais. Mantenha exatamente o ID da variante e o domínio do vendedor retornados. Não presuma que a loja manterá um preço exibido antes. Mostre cada aviso ao lado do produto a que se refere. Essas verificações estão documentadas em Encontrar produtos.
  3. Crie um carrinho quando solicitado. Com a instrução do comprador para reunir itens, chame create_cart para a loja e a variante selecionadas. Um carrinho guarda itens, mas não faz um pedido. Mantenha itens de vendedores diferentes em carrinhos separados: a Shopify diz que cada carrinho e checkout pertence a uma única loja. O resultado deve conter o ID do carrinho e suas linhas. Se o comprador só quiser navegar, pare após a busca; o guia de carrinhos da Shopify diz que o interesse em um produto, por si só, não autoriza criar um carrinho.
  4. Abra e revise o checkout. Quando o comprador pedir o preço total ou estiver pronto para comprar, chame create_checkout usando o ID do carrinho ou o ID exato da variante e o domínio do vendedor retornados na busca. O documento de checkout deve retornar ID, status, itens, moeda, totais, métodos de pagamento, messages, política da loja links e um continue_url para a página da loja. Antes de continuar, mostre ao comprador os totais atuais com seus rótulos, incluindo entrega e impostos, todos os avisos e links de políticas. Mantenha as explicações junto ao item ou campo a que se referem. Forneça ao comprador o continue_url sem alterações, inclusive seus parâmetros de consulta, junto aos itens cobertos, mesmo quando o agente puder concluir o checkout. O checkout pode ficar incomplete se precisar de um endereço ou requires_escalation se o comprador tiver de concluir na página da loja. A Shopify diz que o checkout expira após seis horas por padrão.
  5. Deixe o pagamento com o comprador. Se o comprador entrar, o checkout pode oferecer endereços salvos e Shop Pay. Antes de chamar complete_checkout, leia o checkout mais recente, confirme que está ready_for_complete, mostre a loja, os itens, as quantidades, o total e os métodos disponíveis, e deixe o comprador escolher a forma de pagamento. Não escolha por ele. Mantenha disponível ao comprador o continue_url da loja sem alterações mesmo se o agente puder concluir o checkout; se não houver instrumento de pagamento disponível, o comprador precisa usar esse link. As instruções de checkout da Shopify dizem para enviar complete_checkout uma vez após a aprovação e depois verificar o status retornado. Um fluxo separado de aprovação para lojas fora da Shopify permite que o comprador aprove o pagamento no Shop e forneça um cartão para o checkout próprio da loja; esse não é o fluxo de checkout da loja Shopify descrito nas etapas 3 e 4.
  6. Verifique o resultado. Apenas status: completed com um order confirma que a loja criou um pedido. Se o pagamento ainda estiver sendo processado, use get_checkout para ler o status novamente. A Shopify diz que não há webhooks no lançamento, então uma integração precisa consultar get_checkout para obter atualizações. Se uma chamada de conclusão expirar ou a resposta não for clara, não a envie de novo nem abra um checkout substituto. Leia o checkout existente; se ele não mostrar ambos completed e order, diga ao comprador que a compra não foi confirmada e forneça continue_url.

Limites e recuperação

A Shopify diz que a busca funciona sem credenciais. A nota de lançamento indica aos desenvolvedores que precisam de limites de requisição maiores uma chave de API no Shopify Dev Dashboard, mas não publica preço nem tabela de limites dessa chave. Os preços dos itens da loja, a entrega e os impostos vêm do checkout atual; o comprador deve conferi-los antes de pagar. O agente também pode ter custos próprios de hospedagem ou modelo se o desenvolvedor usar um. O anúncio não quantifica esses custos.

Uma leitura com falha pode ser repetida após qualquer intervalo de retry_after informado. Para criar ou atualizar carrinhos e checkouts, o guia de erros da Shopify recomenda usar uma chave de idempotência e ler o recurso existente antes de repetir uma gravação cujo resultado é incerto. Se uma criação sem chave falhar antes de retornar um ID, o resultado é desconhecido; não tente adivinhar criando outra. complete_checkout é mais rigoroso: nunca o repita após uma resposta incerta. A página da loja continua sendo o caminho do comprador quando requires_escalation ou a falta de dados de pagamento impede a conclusão pelo agente.

Trate IDs de checkout, links de checkout, tokens de acesso e instrumentos de pagamento como dados confidenciais. A Shopify diz que o ID do checkout e continue_url contêm chaves de acesso; mantenha-os fora de logs e análises e compartilhe o link somente com o comprador. A referência de autenticação diz para enviar um token do Shop apenas no cabeçalho de autorização para https://mcp.shop.com/. Um instrumento de pagamento pode conter uma credencial; não o imprima nem registre.

A BIG CHANGE já havia abordado as ferramentas de checkout para agentes de navegador da Shopify. Este lançamento de MCP hospedado descreve um fluxo distinto que começa pela descoberta no catálogo. A nota de lançamento e os manuais da Shopify estabelecem o que os desenvolvedores podem chamar e quais respostas devem conferir; não demonstram ganhos de conversão, confiabilidade sob carga nem uma compra concluída pela BIG CHANGE.

Fontes e leituras adicionais