MCP para assistentes de IA

O Model Context Protocol (MCP) é um protocolo aberto pelo qual um assistente de IA descobre e chama ferramentas de sistemas externos. A Gubee publica um servidor MCP para que um lojista conecte o assistente que ele já usa — ou para que um agente próprio consulte a conta dele — e faça perguntas em linguagem natural sobre o próprio catálogo.

O servidor não é um wrapper da API REST. Ele expõe tools orientadas a resultado: cada uma responde uma pergunta de negócio inteira, já resolvendo as várias chamadas internas necessárias. get_product, por exemplo, devolve produto, variações, atributos e imagens em uma chamada só.

Para quem é

Quem	O que faz	Como conecta
Lojista	Conecta um assistente (Claude e similares) à própria conta e pergunta sobre catálogo, anúncios e pedidos	authorization_code + PKCE, no fluxo de login do assistente
Parceiro / ERP	Escreve um agente próprio que fala MCP e consulta a conta do cliente	client_credentials, com credencial registrada por contrato

Se o que você precisa é sincronização em massa, automação de rotina ou recebimento de eventos, o caminho continua sendo a Referência da API e os Webhooks. O MCP é para consulta conversacional, não para carga.

O que dá para perguntar

As tools de consulta cobrem seis domínios:

• Catálogo — buscar produtos, ver o produto completo com variações, atributos e imagens.
• Anúncios — listar por canal, ver o anúncio completo, exportar em formato de planilha.
• Estoque e preço — posição por armazém, preço de/por por canal e promoções agendadas.
• Pedidos — buscar por período, canal ou situação; ver o pedido completo; exportar.
• Notas fiscais — situação de cada nota de um pedido.
• Diagnóstico — por que um produto não está publicado num canal, e o que falhou numa importação.

O catálogo completo, com os argumentos de cada tool, está em Catálogo de tools. As tools que alteram a conta estão em Alterações pelo MCP.

Alterações

Desde 30/09/2026, além das tools de consulta, o servidor tem 6 tools de alteração: preço padrão de um anúncio, estoque de um SKU num armazém, nome/descrição/atributos de um produto, título/descrição de um anúncio, etiquetas de um anúncio e emissão da nota fiscal de venda de um pedido.

Nenhuma delas escreve na primeira chamada. Toda alteração passa por uma pré-visualização que mostra o antes → depois e devolve um código de confirmação válido por cerca de 10 minutos; só a segunda chamada, com esse código e depois da aprovação do lojista, aplica. Cada alteração exige uma permissão própria, que só é concedida a usuário que a tem no painel da Gubee.

Não há tool de publicação, de exclusão ou de mudança de situação de pedido. O fluxo, o que cada tool altera e o que não altera, as permissões e os erros estão em Alterações pelo MCP.

Garantias de comportamento

Estas são as regras que o servidor segue em toda resposta. Valem para qualquer cliente e não dependem do assistente do outro lado.

O lojista é o do token, sempre

Nenhuma tool aceita identificador de lojista como argumento. O lojista é determinado pela credencial que autenticou a chamada, e não há como pedir dado de outra conta. Uma tool que recebesse sellerId seria uma superfície de vazamento entre contas; por isso não existe.

Resposta parcial se declara parcial

Toda tool que pagina informa, no próprio texto, quantos itens existem no total e como pedir o restante. A primeira página nunca é apresentada como se fosse o conjunto inteiro. O padrão é 10 itens por página, com teto de 50 — um limit maior é reduzido ao teto, e a resposta diz que reduziu.

Falha nunca vira "não encontrei nada"

Se uma consulta interna falhar, a tool devolve erro, com o que não foi possível consultar. Ela não devolve lista vazia. A diferença importa: "o lojista não tem anúncio nesse canal" e "não consegui consultar os anúncios desse canal" levam o assistente a conclusões opostas, e só a segunda pede uma nova tentativa.

O mesmo vale para consultas que dependem do canal em tempo real. Em get_ad, a situação de integração pode não estar disponível (permissão insuficiente na credencial, ou canal fora do ar). Quando isso acontece, a resposta declara explicitamente que não foi possível consultar — nunca deve ser lida como "sem erros".

Dados do comprador saem redigidos

get_order devolve, por padrão, o nome do comprador reduzido, documento e contato mascarados e o endereço apenas com cidade e UF. O argumento includeCustomerData traz o dado completo, e cada uso fica registrado em auditoria. Ligue apenas quando o lojista pedir explicitamente o dado do consumidor.

Datas no fuso do lojista

Toda data e hora de pedido é apresentada em America/Sao_Paulo, o mesmo fuso do painel da Gubee. Datas com hora trazem o fuso escrito na própria resposta, para não haver leitura ambígua. Os argumentos de filtro por data (startDate, endDate) são dias no formato AAAA-MM-DD, também interpretados no fuso do lojista.

Argumento desconhecido é recusado

Se uma chamada trouxer um argumento que a tool não declara, a chamada é recusada com a lista dos nomes não reconhecidos em vez de executada ignorando-os. Um filtro descartado em silêncio produz uma resposta que parece correta e não é — por exemplo, um catálogo inteiro apresentado como se fosse o resultado de uma busca filtrada.

Os nomes de argumento são camelCase em todas as tools (startDate, marketplaceId, includeCustomerData).

Vocabulário

O servidor entrega, no handshake, um glossário do domínio para o assistente. Vale conhecê-lo porque os identificadores são fáceis de confundir:

Termo	O que é
Produto	O item do catálogo do lojista: nome, categoria, variações
Anúncio	A publicação de um produto num canal, com preço e estoque próprios daquele canal
SKU	A variação vendável de um produto (uma combinação de atributos, como tamanho ou cor)
Canal	Onde um anúncio é publicado — também chamado de marketplace ou plataforma

Identificador	Identifica
productId	Um produto no catálogo do lojista
skuId	Uma variação (SKU) de um produto
sku	O código do SKU escrito pelo lojista — não é o skuId
originSkuId	Um SKU no sistema de origem, antes de virar SKU Gubee
adId	Um anúncio publicado num canal
marketplaceId	O código do anúncio no canal (ex.: MLB5183719235) — não é o adId

A distinção entre produto e anúncio está detalhada em Anúncio vs Produto, e a de sku contra skuId em SKU vs skuId.

Próximos passos

1. Conectar um cliente MCP — endpoint, descoberta e autenticação.
2. Catálogo de tools — as 22 tools e seus argumentos.
3. Alterações pelo MCP — como o assistente altera preço, estoque, produto, anúncio, etiquetas e emite nota.