BoostEcom roda um servidor MCP remoto, um endpoint por loja conectada. É a superfície pela qual um cliente de IA lê uma loja Shopify e os dados da BoostEcom associados a ela.
Somente leitura. Cada ferramenta do catálogo é uma leitura, incluindo
a que recebe um documento GraphQL: shopifyAdminGraphQL executa queries
e recusa mutations, pelo nome, no handler. Uma escrita numa loja em
produção é uma decisão que alguém tem de aprovar, e um relay não tem
ninguém dentro: um cliente de IA chama, a chamada chega, nada fica no
meio. Enquanto não houver um caminho de aprovação, recusar é a única
resposta que não pode alterar em silêncio o catálogo de um cliente.
O endpoint
https://boostecom.app/api/mcp/v1/<storeId>
A forma sem versão, /api/mcp/<storeId>, foi lançada primeiro e é
mantida na configuração de todo cliente instalado desde então. Ela
permanece, exatamente como é. As duas são um único endpoint com dois
nomes: os mesmos handlers, e um token gerado por qualquer um dos
dois funciona em ambos.
Use o caminho v1 para qualquer coisa nova.
Dois modos de autenticação
| Modo | Credencial | Famílias de ferramenta que abre |
|---|---|---|
| OAuth 2.1 PKCE | Token de acesso de /oauth/authorize | Relay e native. |
| Estático | Bearer bst_mcp_ | Apenas relay: as 15 ferramentas relay, dentro das permissões Shopify da loja. |
A assimetria é deliberada e explicada em Ferramentas e escopos MCP.
Uma chave estática não carrega nenhuma string de escopos: ela é lida
como a concessão legada, que se expande para a família relay e nada
mais. Isso tem duas consequências. As ferramentas de documentação
public, searchDocs e getDoc, aceitariam um chamador que o relay
não consegue nomear, mas uma chave estática nunca nomeia o escopo delas:
elas não são registradas para ela e só chegam a um cliente via OAuth. E
as ferramentas native nunca são registradas para uma chave estática,
qualquer que seja a concessão, porque exigem um chamador identificado.
O que trava uma ferramenta
Três portões, e uma ferramenta precisa passar por todos para ser registrada em uma dada sessão:
- O escopo BoostEcom aprovado: o que o usuário consentiu.
- Os escopos Shopify da loja: um teto rígido. Se o Custom App ou
a instalação OAuth nunca obteve
read_orders, nenhum escopo BoostEcom o conjura. - Um chamador identificado: exigido apenas por ferramentas
native, porque sua permissão depende de uma associação a uma organização e não há ninguém para verificar no modo estático.
Uma ferramenta que falha em qualquer portão não é registrada: ela não aparece na lista de ferramentas do cliente de jeito nenhum, em vez de aparecer e falhar na chamada. Esse é o comportamento correto para um cliente de IA: uma ferramenta que ele pode ver é uma ferramenta que ele vai tentar.
Conectando um cliente
Quatro clientes têm um guia passo a passo:
Cada um fornece a URL, o modo de autenticação que aquele cliente suporta, e um trecho de configuração pronto para colar.
Descoberta de agentes
A plataforma publica um perfil de agente UCP em
/.well-known/ucp-agent. Ele declara
capacidade de leitura de catálogo e não carrega segredos. É o que
toda loja Shopify que consultamos lê para negociar nossas capacidades
antes de responder.
A seguir
- Ferramentas e escopos MCP: o catálogo completo.
- Autenticação: escolhendo uma credencial.