Pular para conteúdo

Alterações pelo MCP

Além das 16 tools de consulta, o servidor MCP da Gubee oferece 6 tools que alteram a conta do lojista: preço, estoque, produto, anúncio, etiquetas de anúncio e emissão de nota fiscal. Desde 30/09/2026, as seis estão disponíveis em produção.

Cada chamada altera uma coisa: um anúncio, um SKU num armazém, um produto ou um pedido. Não há alteração em lote pelo MCP — para carga, use a Referência da API.

Dois passos: pré-visualização e confirmação

Nenhuma tool de alteração escreve na primeira chamada. Toda alteração passa por dois passos.

  1. Pré-visualização. O assistente chama a tool sem o argumento confirmation. Nada é alterado. A resposta traz o antes → depois, o efeito da alteração e um código confirmation.
  2. Confirmação. O assistente mostra o antes → depois ao lojista. Só depois que o lojista aprovar explicitamente, na conversa, o assistente chama a mesma tool de novo, com os mesmos argumentos e o confirmation recebido.

Regras do código de confirmação:

  • Vale por cerca de 10 minutos. A resposta da pré-visualização informa até que horas (horário de Brasília). Depois disso, é preciso pré-visualizar de novo.
  • Está amarrado ao que foi pré-visualizado: ao mesmo usuário, ao mesmo cliente MCP, à mesma tool e aos mesmos argumentos. Trocar um valor exige nova pré-visualização.
  • Está amarrado ao valor de antes. Na confirmação, o servidor lê o valor atual de novo. Se ele mudou desde a pré-visualização (alguém alterou pelo painel, por exemplo), a alteração é recusada e nada muda.

O código não é a aprovação do lojista

O confirmation prova que houve uma pré-visualização com aqueles valores. Ele não prova que uma pessoa aprovou. Quem garante a aprovação é o assistente: nunca confirme sem o lojista ter visto e aprovado o antes → depois. Se você escreve um agente próprio, essa regra é sua.

Confirmação adicional do aplicativo

Alguns aplicativos exibem, no momento da confirmação, uma pergunta de sim/não montada pelo próprio servidor da Gubee — o modelo não responde por você. Se o lojista recusar ou cancelar, nada é alterado.

Para título e descrição, a pergunta não repete o texto novo: mostra o tamanho e um código curto de conferência, o mesmo que a pré-visualização exibiu. Confira se os dois batem.

Nem todo aplicativo exibe essa pergunta. Quando não exibe, a proteção é a pré-visualização, o código de confirmação e a aprovação de uso de ferramenta do próprio aplicativo: todas as tools de alteração se declaram como não somente leitura e destrutivas, para que o aplicativo possa pedir autorização antes de chamá-las.

As tools

Tool O que altera Argumentos Permissão
update_price O preço padrão de um anúncio adId, price, confirmation price:edit
update_stock A quantidade total de um SKU num armazém sku, quantity, warehouseId, confirmation stock:edit
update_product Nome, descrição e valores de atributos de um produto productId, name, description, attributes, confirmation product:edit
update_ad Título e descrição de um anúncio adId, title, description, confirmation ad:edit
manage_ad_tags Etiquetas de organização de um anúncio adId, operation, tags, confirmation ad:edit
issue_invoice Emite a NF-e de venda de um pedido orderId, confirmation invoice:issue

update_price — preço padrão

Altera o preço padrão (o preço "de") de um anúncio. É a mesma alteração do card do anúncio no painel da Gubee.

  • Não altera preço promocional. Os promocionais do anúncio são regravados como estão. Se houver um promocional vigente, o canal continua cobrando o promocional, e o padrão passa a ser só o "de". A pré-visualização mostra o preço de venda antes → depois e avisa quando o padrão muda mas o preço de venda não.
  • Recusa preço padrão menor que um promocional, porque o serviço de preços não aceita. A recusa informa o menor preço padrão possível. Para ir abaixo disso, ajuste ou remova a promoção pelo painel.
  • Recusa anúncio em campanha, anúncio pai de variações (use o adId de cada variação) e anúncio cujo preço vem do produto.
  • price é em reais, com ponto decimal e no máximo duas casas (129.90). A mudança não pode passar do limite de variação por operação; a pré-visualização informa o limite.
  • A atualização é assíncrona: o preço pode levar alguns instantes para aparecer em get_ad e chegar ao canal.

update_stock — estoque de um armazém

Define a quantidade total (estoque físico) de um SKU em um armazém. É a mesma alteração da edição rápida de estoque do painel: vira uma movimentação de ajuste, positiva ou negativa, pela diferença entre o total atual e o novo.

  • quantity é o total, não o disponível. Disponível = total − reservado para pedidos, e as reservas não mudam. Para chegar a um disponível desejado, informe total = disponível desejado + reservado. A pré-visualização mostra total, reservado e disponível antes → depois.
  • O total não pode ficar abaixo do reservado, e há um limite por operação.
  • warehouseId é o armazém como get_stock o mostra. É obrigatório quando o SKU tem estoque em mais de um armazém.
  • Não altera estoque de kit (calculado pelos componentes) e não cria estoque em armazém onde o SKU ainda não tem registro.

Não repita a confirmação de estoque

A movimentação soma ao estoque. Depois de aplicada, não chame de novo com o mesmo confirmation: confira o resultado com get_stock.

update_product — nome, descrição e atributos

Altera o nome, a descrição e/ou os valores de atributos que um produto do catálogo já tem. É a mesma gravação da tela de edição de produto do painel.

  • Preço e estoque não mudam. Também não mudam imagens, categoria, marca e variações.
  • Não cria nem remove atributo. attributes é um objeto: nome exato do atributo (como get_product mostra) → lista com os valores novos, que substituem os atuais. Até 20 atributos, de 1 a 30 valores cada. Atributos não citados não mudam.
  • name: de 3 a 150 caracteres, numa linha só. description: de 3 a 5.000 caracteres. Omita o campo que não quer mudar.
  • Não vale para produto kit. Em produto com variações, a descrição só se edita pelo painel.

update_ad — título e descrição de um anúncio

Troca o título e/ou a descrição de um anúncio, só naquele canal e naquela conta. Os outros anúncios do mesmo produto não mudam.

  • Preço, estoque, imagens e os demais dados do anúncio não mudam.
  • O limite do título é o do canal (no Mercado Livre, de 5 a 100 caracteres). A descrição aceita texto ou HTML simples de formatação, sem script, iframe, object, embed nem atributo on…=, até 5.000 caracteres na maioria dos canais.
  • Não vale para variação (use o anúncio pai), anúncio finalizado e anúncio cujo texto vem de template.

manage_ad_tags — etiquetas do anúncio

Adiciona (operation: ADD) ou remove (REMOVE) etiquetas de organização de um anúncio. É a mesma alteração de "Atualizar tags" na lista de anúncios do painel.

  • Não altera preço, estoque, título nem outro dado do anúncio, mas aplicar reenvia o anúncio inteiro ao canal: a situação de integração volta a pendente até o canal responder. A pré-visualização avisa.
  • De 1 a 10 etiquetas por vez, cada uma com até 50 caracteres: letras, números, espaço, ponto, hífen e sublinhado (sem vírgula). Maiúsculas e minúsculas contam — use a grafia exata de uma etiqueta existente.
  • Etiquetas do sistema (catálogo, integração, campanha, preço, conteúdo) não podem ser adicionadas nem removidas pelo MCP — só pelo painel.
  • Não vale para variação de anúncio. No anúncio pai de variações, a etiqueta vai só no pai.
  • get_ad ainda não mostra etiquetas. Para conferir, faça uma nova pré-visualização (sem confirmation) ou veja no painel.

issue_invoice — nota fiscal de venda

Solicita a emissão da NF-e de venda de um pedido. É a mesma solicitação de "Gerar nota" em Notas fiscais no painel. A loja emissora é escolhida pelo emissor, pelo canal e pela conta do pedido.

  • Só emite para pedido pago, que não seja de fulfillment e que ainda não tenha nota de venda no emissor (em qualquer situação, menos cancelada).
  • A autorização da SEFAZ é assíncrona. Acompanhe pelo painel e, depois de autorizada, com get_invoices.

Emitir nota é ato fiscal

Depois de autorizada, a nota só se desfaz por cancelamento, que exige justificativa e tem prazo. A emissão não é idempotente: depois de aplicada, não chame de novo.

O ciclo de vida da nota está em Notas Fiscais e DANFE.

Repetir uma confirmação

Tool Repetir o mesmo confirmation
update_price Reenvia o preço ao canal e, se o preço tiver voltado ao valor de antes, grava o novo de novo. Só repita se get_ad continuar mostrando o valor antigo depois de alguns minutos
update_stock Não repita. Confira com get_stock
update_product Seguro: a alteração é absoluta, não acumula
update_ad Seguro: a Gubee reconhece a repetição e não reenvia
manage_ad_tags Seguro: adicionar etiqueta presente ou remover ausente não muda nada
issue_invoice Não repita. Confira em Notas fiscais no painel

Permissões

Cada domínio de alteração tem uma permissão OAuth própria, pedida junto com as de consulta na conexão do cliente:

Permissão Tools
price:edit update_price
stock:edit update_stock
product:edit update_product
ad:edit update_ad, manage_ad_tags
invoice:issue issue_invoice
  • O usuário precisa ter a permissão correspondente no painel da Gubee. Sem ela, a permissão não é concedida no login, mesmo que o assistente a peça — o login segue normalmente, sem as permissões de alteração.
  • A pré-visualização lê o estado atual, então cada tool também precisa da permissão de consulta do que ela lê: ad:view para update_price, update_ad e manage_ad_tags; stock:view para update_stock; product:view para update_product; order:view e invoice:view para issue_invoice.
  • As tools aparecem em tools/list para qualquer conexão. Quem não tem a permissão recebe a recusa na chamada, antes de qualquer consulta ou alteração.
  • A tool só altera recursos do lojista do token. Um recurso de outro lojista é recusado.

Erros comuns

Toda recusa diz, no próprio texto, que nada foi alterado. O resultado incerto é o único caso em que não se sabe — e ele diz isso.

Mensagem (resumo) Causa O que fazer
O seu usuário não tem a permissão … no painel da Gubee O usuário não tem a permissão de alteração no painel Um administrador da conta concede a permissão ao usuário. Reconectar o assistente não resolve
A autorização deste cliente MCP não inclui a permissão … O assistente não pediu a permissão, ou ela não foi autorizada no login Acrescente a permissão à configuração e reconecte, autorizando-a
O código de confirmação expirou Passaram-se mais de ~10 minutos desde a pré-visualização Pré-visualize de novo e confirme com o código novo
O código de confirmação não é válido Código alterado, truncado ou inventado Pré-visualize de novo
…emitido para outra operação ou outros valores A confirmação trouxe argumentos diferentes dos pré-visualizados Pré-visualize com os valores que quer aplicar
…emitido para outro usuário ou outro cliente MCP O código veio de outra conexão Pré-visualize de novo nesta conversa
O valor atual mudou desde a pré-visualização O recurso foi alterado entre os dois passos Pré-visualize de novo para ver o antes → depois atualizado
O preço promocional … é maior que o novo preço padrão update_price com padrão abaixo de um promocional Escolha um padrão de pelo menos o valor informado, ou ajuste a promoção pelo painel
Não aplicado: a confirmação foi recusada ou cancelada no seu aplicativo O lojista recusou a confirmação adicional Nada a fazer; nada mudou
Resultado incerto / Não sei se a alteração … foi aplicada A chamada saiu, mas a resposta não confirmou o resultado Confira com a tool de leitura (get_ad, get_stock, get_product, ou Notas fiscais no painel) antes de qualquer nova tentativa, e siga a tabela Repetir uma confirmação

Um resultado incerto nunca é apresentado como falha. A escrita pode ter acontecido; por isso a regra é conferir antes de repetir — e, em estoque e nota fiscal, não repetir.

Próximos passos