A Shopify lançou o Shop MCP a 13 de outubro, dando aos programadores uma ligação alojada para pesquisar produtos, usar carrinhos e fazer checkout. O serviço está em https://mcp.shop.com/. As suas 17 ferramentas podem encontrar produtos no Shopify Catalog e abrir o checkout do comerciante que vende um artigo. A pesquisa no catálogo não exige uma chave de API. Uma compra real continua a exigir a aprovação do comprador.

Este guia destina-se a programadores que configuram um assistente compatível com MCP. Os passos seguem a documentação da Shopify, consultada a 14 de outubro. A BIG CHANGE não ligou um agente, criou um carrinho nem fez uma compra. Por isso, o guia descreve resultados esperados, não desempenho observado.

A principal mudança

  • O que mudou: A Shopify oferece agora uma ligação MCP alojada que vai da pesquisa no catálogo ao carrinho do comerciante e ao checkout. Também documenta a conclusão com Shop Pay para um comprador com sessão iniciada, após confirmação explícita.
  • Quem pode usar: Programadores 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 só usa o handshake initialize não consegue ligar-se diretamente.
  • O que verificar: Um checkout é uma transação com um único comerciante. completed juntamente com um order confirma a compra; um carrinho, uma ligação de checkout ou um pagamento em curso não o fazem.

Antes de ligar

Precisa de um cliente MCP que suporte servidores HTTP remotos e o método de ligação documentado pela Shopify ou de uma aplicação que chame o servidor por HTTP. Use o URL de raiz https://mcp.shop.com/; acrescentar /mcp devolve um erro 404. As ferramentas de pesquisa e carrinho funcionam sem uma conta Shop. Ao iniciar sessão, o assistente pode usar preferências e moradas guardadas, encontrar encomendas e oferecer Shop Pay quando o comerciante o disponibiliza. Para um assistente com código HTTP próprio, a Shopify documenta um fluxo OAuth para dispositivos que o comprador aprova no site Shop.

Escolha uma consulta de produto, o país de destino e a moeda antes de pesquisar. Separe os requisitos indicados pelo comprador do contexto da pesquisa: o país ou a moeda ajudam a localizar os resultados; o limite de preço, o tamanho ou o destino de envio são filtros. A API apresenta os preços nas unidades menores da moeda. A aplicação deve ler o campo messages da resposta antes de afirmar que um resultado cumpre um filtro, pois o serviço pode indicar que o filtro não foi aplicado como pedido. O guia de pesquisa da Shopify explica a diferença e o limite de 1 a 50 resultados por página.

Um percurso documentado da pesquisa à encomenda

  1. Ligue e verifique a pesquisa. Configure o cliente com https://mcp.shop.com/ e carregue o Shop skill da Shopify, se o cliente o suportar. A Shopify sugere testar a ligação pedindo três candeeiros de secretária sem criar um carrinho. Uma pesquisa funcional devolve produtos com vendedor, preço numa moeda indicada e ligação do comerciante. Os programadores que usam HTTP podem seguir o guia rápido JSON-RPC da Shopify, que inclui os cabeçalhos de protocolo necessários e o pedido search_catalog. Esta verificação é só de leitura e não exige início de sessão.
  2. Escolha o artigo certo. Execute search_catalog com a consulta e os requisitos do comprador. A pesquisa devolve uma variante em destaque; use get_product se o comprador quiser outro tamanho ou cor. Compare product.selected e a variant.options devolvida com cada tamanho, cor e outra opção especificada pelo comprador antes de a mostrar ou comprar. A Shopify afirma que a seleção pode ser flexibilizada sem aviso. Quando o comprador escolhe um produto ou altera uma opção, volte a chamar get_product para verificar a disponibilidade e o preço atuais. Mantenha exatamente o ID da variante e o domínio do vendedor devolvidos. Não parta do princípio de que o comerciante mantém um preço anteriormente apresentado. Mostre cada aviso junto ao produto a que diz respeito. Estas verificações estão documentadas em Encontrar produtos.
  3. Crie um carrinho quando for pedido. Com a instrução do comprador para reunir artigos, chame create_cart para o comerciante e a variante selecionados. Um carrinho guarda artigos, mas não faz uma encomenda. Mantenha artigos de vendedores diferentes em carrinhos separados: a Shopify diz que cada carrinho e checkout pertence a um único comerciante. O resultado deve incluir o ID do carrinho e as respetivas linhas. Se o comprador só quiser explorar, pare depois da pesquisa; o guia de carrinhos da Shopify diz que o interesse num produto, por si só, não autoriza a criação de um carrinho.
  4. Abra e reveja o checkout. Quando o comprador pedir o preço total ou estiver pronto para comprar, chame create_checkout com o ID do carrinho ou o ID exato da variante e o domínio do vendedor devolvidos pela pesquisa. O documento de checkout deve devolver um ID, estado, artigos, moeda, totais, métodos de pagamento, messages, política do comerciante links e uma continue_url para a página do comerciante. Antes de avançar, mostre ao comprador os totais atuais com os respetivos rótulos, incluindo entrega e impostos, todos os avisos e ligações para políticas. Coloque as explicações junto ao artigo ou campo a que dizem respeito. Dê ao comprador a continue_url inalterada, incluindo os parâmetros da consulta, juntamente com os artigos abrangidos, mesmo que o agente consiga concluir o checkout. O checkout pode ficar incomplete se precisar de uma morada, ou requires_escalation se o comprador tiver de o concluir na página do comerciante. A Shopify diz que o checkout expira, por predefinição, após seis horas.
  5. Deixe o pagamento a cargo do comprador. Se o comprador iniciar sessão, o checkout pode oferecer moradas guardadas e Shop Pay. Antes de chamar complete_checkout, leia o checkout mais recente, confirme que está ready_for_complete, mostre o comerciante, artigos, quantidades, total e métodos disponíveis, e deixe o comprador escolher o método de pagamento. Não escolha por ele. Mantenha a continue_url inalterada do comerciante disponível para o comprador, mesmo que o agente consiga concluir o checkout; se não houver instrumento de pagamento disponível, o comprador tem de usar essa ligação. As instruções de checkout da Shopify dizem para enviar complete_checkout uma vez após a aprovação e depois inspecionar o estado devolvido. Um fluxo de aprovação separado para lojas fora da Shopify pede ao comprador que aprove o pagamento na Shop e forneça um cartão para o checkout próprio dessa loja; não é o checkout do comerciante Shopify descrito nos passos 3 e 4.
  6. Verifique o resultado.Apenas status: completed com um order confirma que o comerciante criou uma encomenda. Se o pagamento ainda estiver a ser processado, use get_checkout para voltar a ler o estado. A Shopify afirma que não há webhooks no lançamento, pelo que uma integração tem de 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 novamente nem abra um checkout substituto. Leia o checkout existente; se não mostrar ambos completed e order, diga ao comprador que a compra não está confirmada e forneça-lhe continue_url.

Limites e recuperação

A Shopify afirma que a pesquisa funciona sem credenciais. A sua nota de lançamento encaminha os programadores que precisam de limites de pedidos mais elevados para uma chave de API no Shopify Dev Dashboard, mas não publica o preço nem uma tabela de limites para essa chave. Os preços dos artigos do comerciante, o envio e os impostos vêm do checkout atual; o comprador deve revê-los antes de pagar. O agente também pode ter custos próprios de alojamento ou modelo, se o programador usar um. O anúncio não quantifica esses custos.

Uma leitura falhada pode ser repetida após qualquer intervalo de retry_after indicado. Para criar ou atualizar carrinhos e checkouts, o guia de erros da Shopify recomenda uma chave de idempotência e a leitura do recurso existente antes de repetir uma escrita cujo resultado seja incerto. Se um pedido de criação sem chave falhar antes de devolver um ID, o resultado é desconhecido; não tente adivinhar criando outro. complete_checkout é mais rigoroso: nunca o repita depois de uma resposta incerta. A página do comerciante continua a ser o percurso do comprador quando requires_escalation ou a falta de dados de pagamento impede o agente de concluir.

Trate os IDs de checkout, ligações de checkout, tokens de acesso e instrumentos de pagamento como dados sensíveis. A Shopify diz que o ID de checkout e continue_url contêm chaves de acesso; mantenha-os fora dos registos e da analítica e partilhe a ligação apenas com o comprador. A referência de autenticação diz para enviar um token 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 registe.

A BIG CHANGE já tinha abordado as ferramentas de checkout de agentes de navegador da Shopify. Esta versão MCP alojada descreve um fluxo separado que começa pela descoberta no catálogo. A nota de lançamento e os manuais da Shopify estabelecem o que os programadores podem chamar e que respostas devem inspecionar; não demonstram aumentos de conversão, fiabilidade sob carga nem uma compra efetuada pela BIG CHANGE.

Fontes e leituras adicionais