AI-translated from English; not yet reviewed by a fluent editor. # Como conectar um agente de compras ao Shop MCP da Shopify > O novo Shop MCP da Shopify conecta a busca no catálogo, os carrinhos das lojas e o checkout. Este guia baseado na documentação explica a configuração, a aprovação do comprador e os limites para confirmar um pedido. By BIG CHANGE Editorial Published: 2026-10-14T12:58:17.853Z Updated: 2026-10-14T12:58:17.853Z Canonical: https://bigchange.ai/blog/connect-shopping-agent-shopify-shop-mcp ![Conceptual charcoal illustration of a product shelf, a shopping basket holding one cup, and a blank checkout terminal; a shopper's hand pauses short of the terminal.](https://bigchange.ai/api/media/file/shop-mcp-catalog-to-checkout-hero-v1.png) AI-generated conceptual illustration by BIG CHANGE; no actual Shop MCP interface, agent test or purchase is depicted. A Shopify [lançou o Shop MCP em 13 de outubro](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp), 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](https://shop.dev/docs/connect) 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](https://shop.dev/docs/search) 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](https://shop.dev/docs/connect) 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](https://shop.dev/docs/quickstart) 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](https://shop.dev/docs/search). 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](https://shop.dev/docs/checkout) 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](https://shop.dev/docs/checkout) 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](https://shop.dev/docs/approvals) 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](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp) 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](https://shop.dev/docs/errors) 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](https://shop.dev/docs/authentication) 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](https://bigchange.ai/blog/shopify-webmcp-browser-agent-checkout) 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 - [Changelog para desenvolvedores da Shopify, “Adicione compras e checkout com Shop Pay a qualquer agente usando Shop MCP”, 13 de outubro de 2026](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp). Escopo do lançamento, endpoint hospedado, 17 ferramentas, acesso à busca, caminhos de checkout e situação dos webhooks no lançamento. - [Visão geral do Shop MCP e guia de conexão](https://shop.dev/docs/). Protocolo atual, requisitos do cliente e login. - [Shopify, Encontrar produtos](https://shop.dev/docs/search). Campos de busca, seleção de variantes, unidades de preço e avisos de filtros. - [Shopify, Carrinhos e checkout](https://shop.dev/docs/checkout). Escopo da loja, significados dos status, conclusão do checkout e tratamento de resultados incertos. - [Shopify, Erros e novas tentativas](https://shop.dev/docs/errors). Regras de recuperação de leitura e gravação. - [Shopify, Autenticação](https://shop.dev/docs/authentication). Acesso à conta Shop e tratamento de tokens. ## Sources - [Changelog para desenvolvedores da Shopify, Adicione compras e checkout com Shop Pay a qualquer agente usando Shop MCP](https://shopify.dev/changelog/posts/add-shopping-and-shop-pay-checkout-to-any-agent-with-shop-mcp) — Data de lançamento, endpoint ativo, 17 ferramentas, busca no catálogo sem chave, caminhos de checkout Shop e fora da Shopify, ausência de webhooks no lançamento e chave do Dev Dashboard para limites maiores. São afirmações da Shopify, não resultados independentes. - [Visão geral do Shop MCP](https://shop.dev/docs/) — Endpoint hospedado, versão MCP de 2026-07-28, versão do documento UCP de 2026-08-25, uma loja por checkout e confirmação de pedido concluído. - [Shop MCP, Conectar um agente](https://shop.dev/docs/connect) — URL raiz e requisito de protocolo, caminhos para clientes, carregamento da skill e verificação de conexão somente leitura. - [Shop MCP, Início rápido](https://shop.dev/docs/quickstart) — Solicitação de busca JSON-RPC documentada, cabeçalhos, formato da resposta, unidades de preço e erros. - [Shop MCP, Encontrar produtos](https://shop.dev/docs/search) — Consulta, filtros, contexto, variante em destaque e avisos. - [Shop MCP, Carrinhos e checkout](https://shop.dev/docs/checkout) — Comportamento das ferramentas de carrinho e checkout, escopo da loja, campos e status do checkout, aprovação humana do pagamento, IDs confidenciais e tratamento de conclusão incerta. - [Shop MCP, Erros e novas tentativas](https://shop.dev/docs/errors) — Recuperação de leitura, chave de idempotência para gravações que não sejam pagamentos e proibição de repetir complete_checkout após resultado incerto. - [Shop MCP, Autenticação](https://shop.dev/docs/authentication) — Escopo do token Shop, fluxo OAuth para dispositivo e proteção de credenciais privadas. - [Shop MCP, Aprovar uma compra fora da Shopify](https://shop.dev/docs/approvals) — Caminho separado de aprovação do comprador e cartão para checkout de uma loja que não usa Shopify.