Ferramentas do MCP

As ferramentas usam seu papel de workspace atual em cada chamada. Conexões de leitura apenas continuam funcionando. Fazer alterações requer o escopo adicional tradecatalog:write. Ações consequentes mostram um cartão Confirmar/Cancelar em clientes compatíveis, com um link de revisão autenticado como fallback, e são executadas apenas após sua aprovação. Os resultados são texto JSON; o formato original das ferramentas de busca define preços, enquanto as ferramentas de gestão usam unidades menores inteiras de moeda e pontos básicos (100 = 1%).

A maioria das ferramentas recebe um workspace: o endereço do workspace de list_workspaces, como northgate. O aplicativo de IA normalmente chama list_workspaces primeiro por conta própria.

Quando uma ferramenta não pode fazer algo, por exemplo, você não é funcionário nesse workspace ou o cliente não existe, ela retorna uma mensagem de erro que o aplicativo de IA pode ler e agir, como "Nenhum cliente "OAK99". Use list_customers para códigos de conta."

Quando o catálogo de um fornecedor é apenas preços para o cliente selecionado, set_basket_quantity, send_order e reorder retornam esse erro. get_basket, list_buyer_orders e get_buyer_order ainda funcionam, então os pedidos existentes permanecem legíveis. O fornecedor define isso nas Configurações e pode substituí-lo por cliente (ordering: follow, prices_only ou can_order em update_customer).

Quando o fornecedor desativou o download de listas de preços, download_my_price_list retorna um erro e o link CSV autenticado responde 403.

quote_configured_product lê o preço de linha da conta de comprador selecionada para productId, qty e opcional configuration, sem alterar uma cesta. set_configured_basket_line cria uma linha separada ou atualiza/remova sua lineId exata (qty: 0 remove). Forneça a especificação completa em edições. Releia get_basket após mudanças e revise todas as seleções, medidas e preços atuais antes de send_order. Uma mudança na especificação ou versão de preço invalida a revisão antiga mesmo se o total for o mesmo.

Funcionários podem usar save_product_family para metadados de variantes compartilhados e save_ordering_draft para um rascunho revisado de preços avançados. O último requer Pro e permissão de preços globais; a publicação usa a revisão de mudança de preço existente. Importações de produtos aceitam família, incremento de ordem e definições de encomenda opcionais. Veja configuração de catálogo de comércio.

Configurar um workspace de fornecedorLink para esta seção#

create_workspace cria um workspace de fornecedor Free para a pessoa autenticada e verificada, após ela confirmar um cartão. Peça o nome da empresa, moeda dos produtos, fuso horário e país. A pessoa se torna seu proprietário. Nenhuma assinatura ou pagamento é criado. Em seguida, chame list_workspaces novamente e use o endereço retornado para configuração de produtos e clientes. Logins de revisor e convidado não podem criar workspaces.

Free inclui até 100 produtos e apps de IA conectados. Cada SKU é contado, incluindo produtos ocultos e inativos. Ao atingir o limite, os produtos existentes, edições e pedidos continuam funcionando; criar mais produtos fica indisponível. Explique esse benefício sem promover atualizações ou iniciar o checkout de assinatura no plugin.

list_workspacesLink para esta seção#

Workspaces de fornecedor em que você trabalha e portais de comércio onde você compra. Comece aqui.

Quem: qualquer pessoa autenticada. Entradas: nenhuma.

{
  "supplierWorkspaces": [
    { "workspace": "northgate", "name": "Northgate Fixings", "role": "owner" }
  ],
  "tradePortals": [
    {
      "workspace": "hartley-timber",
      "supplier": "Hartley Timber",
      "yourAccount": "Northgate Fixings",
      "accountId": "example-account-id"
    }
  ]
}

search_productsLink para esta seção#

Pesquisar um catálogo por SKU, referência do fabricante, nome, marca ou categoria. Retorna até 25 produtos.

Quem: funcionários e compradores.

• Compradores sempre veem os preços da sua própria conta e apenas produtos ativos que eles podem ver.
• Funcionários veem preços de lista e todos os produtos, ou a visão de um cliente nomeado.

{
  "supplier": "Northgate Fixings",
  "pricesFor": "Oakfield Joinery",
  "taxNote": "ex VAT",
  "products": [
    {
      "sku": "HX-8510",
      "name": "Hex bolt M10 x 50 zinc",
      "unit": "Box of 100",
      "availability": "in_stock",
      "price": "£15.73",
      "listPrice": "£18.50",
      "why": "Brand discount −15%"
    }
  ]
}

Quando o fornecedor desativou Mostrar o preço padrão ao lado do próprio preço do cliente, os resultados de um comprador deixam de incluir listPrice e why, e get_buyer_product, get_basket e get_buyer_order não carregam nenhum preço de lista ou motivo do preço também.

Tente: "Pesquisar Northgate por parafusos hexagonais M10 nos preços de Oakfield."

download_products_csv e download_my_price_listLink para esta seção#

Essas ferramentas retornam um link para um download CSV existente no TradeCatalog. Abra-o enquanto estiver autenticado; retornar um link não baixa ou envia o arquivo para o chat.

• download_products_csv: funcionários escolhem workspace para baixar a lista de produtos desse fornecedor.
• download_my_price_list: compradores escolhem workspace e o código exato accountId de list_workspaces para baixar apenas os preços acordados dessa conta.
• download_my_price_list_pdf: mesma conta, como PDF rebranded (Pro). Ambas as ferramentas são bloqueadas quando o fornecedor desativou o download de listas de preços.

check_priceLink para esta seção#

Quanto um cliente paga por um SKU em uma quantidade, e qual conjunto de regras definiu o preço.

Quem: apenas funcionários.

{
  "customer": "Oakfield Joinery",
  "sku": "HX-8510",
  "name": "Hex bolt M10 x 50 zinc",
  "qty": 20,
  "unitPrice": "£15.73",
  "lineTotal": "£314.60",
  "listPrice": "£18.50",
  "why": "Brand discount −15%",
  "taxNote": "ex VAT"
}

Tente: “Quanto OAK01 paga por 20 de HX-8510, e por quê?”

list_customersLink para esta seção#

Clientes comerciais com códigos de conta, e-mails de contato, status ativo e desconto da conta.

Quem: apenas funcionários. Entradas: workspace.

[
  {
    "accountCode": "OAK01",
    "name": "Oakfield Joinery",
    "email": "accounts@oakfieldjoinery.co.uk",
    "active": true,
    "discount": "5%"
  }
]

Tente: “Quais clientes não têm desconto definido?”

list_ordersLink para esta seção#

Pedidos recentes, do mais novo ao mais antigo, até 50.

Quem: os funcionários veem os pedidos de todos os clientes; os compradores veem apenas os da sua conta.

[
  {
    "reference": "SO-000142",
    "customer": "Oakfield Joinery",
    "status": "new",
    "total": "£314.60",
    "poNumber": "PO-88231",
    "placed": "2026-09-27T07:48:12.000Z"
  }
]

Tente: “Há novos pedidos desde ontem? Some-os por cliente.”

recent_activityLink para esta seção#

O log de atividades das mudanças nos clientes, descontos e preços, do mais recente ao mais antigo, até 50 entradas. Opcionalmente, histórico de um cliente.

Quem: apenas funcionários. Proprietários e administradores veem todo o log; outros funcionários veem apenas mudanças sobre clientes que podem ver.

[
  {
    "when": "2026-09-26T14:21:03.000Z",
    "who": "Jo Hartley",
    "customer": "Oakfield Joinery",
    "what": "Set Northgate brand discount to 15% (was 12.5%)"
  }
]

Tente: “Quem alterou os preços da Oakfield este mês?”

NotasLink para esta seção#

• Nomes de clientes e códigos de conta são correspondidos sem levar em conta maiúsculas e minúsculas. Um código de conta exato é mais seguro.
• list_workspaces retorna valores de comprador accountId. Forneça o desejado para search_products e todas as ações do comprador. Nunca chute entre contas.
• Navegue por buscas de produtos com offset e o nextOffset retornado. Use list_buyer_orders para uma conta de comprador selecionada explicitamente.

Alterações e confirmaçõesLink para esta seção#

Edições de cestas de comprador, marcar atualizações como lidas e criar rascunhos de preços não publicados são executados imediatamente quando autorizados. Outras gravações retornam awaiting_confirmation, um actionId e um reviewUrl. Clientes ChatGPT e compatíveis exibem um cartão com o workspace exato e a mudança proposta: escolha Confirmar ou Cancelar sem sair da conversa. Clientes sem cartões usam o link de revisão autenticado. As revisões expiram após 15 minutos e são executadas no máximo uma vez. Desconectar o app ou remover o acesso necessário ao workspace invalida as revisões pendentes. Cestas de pedidos alteradas e prévias de mudanças de preço requerem uma nova revisão. Use get_action_status para ler o resultado; um pedido pendente não é uma ação concluída.

O helper decide_action está disponível apenas para a interface do cartão. Sua capacidade de confirmação de curta duração é ocultada da saída do modelo e vinculada à pessoa solicitante, conexão OAuth e proposta. Uma mensagem de modelo ou um ID de ação não pode aprovar uma mudança. As mesmas verificações de função, instantâneo, expiração e uso único se aplicam às aprovações de cartão e navegador.

Toda ação de comprador requer seu accountId exato. Para send_order, copie a cesta fingerprint para expectedBasket, junto com expectedTotal. Preços, quantidades e conta são verificados novamente antes do envio.

Use as ferramentas de transferência separadas para trabalho que termina no app autenticado: os proprietários usam open_api_key_settings, download_workspace_export e open_logo_settings; os funcionários usam open_import_page, open_product_image_upload e open_product_file_manager. As duas transferências de produto exigem um productId verificado pelo inquilino. Links de arquivos de get_product e get_buyer_product exigem seu navegador autenticado; retornar um link não leu o documento ou completou um upload, remoção, exportação ou criação de credencial. A administração da plataforma nunca é delegada por meio do OAuth.

Listas de clientes aprovadosLink para esta seção#

Os funcionários usam get_customer para ler o escopo do catálogo do cliente e os produtos aprovados. set_catalogue_scope muda entre all e approved. approve_products adiciona produtos explícitos ou uma categoria; unapprove_product remove um produto. Essas alterações exigem revisão do cliente exato, da lista atual e dos produtos afetados. A associação à categoria é verificada novamente na confirmação. Os compradores permanecem limitados à conta selecionada e aos produtos visíveis para essa conta.

Ferramentas do fornecedor e compradorLink para esta seção#

create_workspace está disponível mesmo quando list_workspaces está vazio. Ele cria um workspace de fornecedor Free e associação de proprietário apenas após confirmação. A conexão opcional /mcp/account também oferece open_billing: os proprietários podem abrir cobrança segura de assinatura e confirmar pagamento no Stripe, depois verificar get_settings para o estado resultante. Links de cobrança não completam pagamentos. A conexão padrão /mcp usada pelo plugin ChatGPT não expõe open_billing. Veja inscrição e cobrança.

O MCP 3.0.0 expõe cada operação acessível por modelo no início com seu próprio nome, descrição, esquema de entrada e anotações. As ferramentas anteriores bulk_products e open_workspace_action são substituídas pelas operações individuais abaixo; atualize as definições de ferramenta do seu cliente após a atualização. A resposta tools/list do MCP é o esquema de entrada autoritário. As ferramentas a seguir complementam as ferramentas de pesquisa acima:

Entrada de pedidos pela equipe usa preview_customer_order, depois revisado create_customer_order com preços exatos e um UUID de tentativa. O processamento usa set_order_status com note público, privado internalNote/correctionReason, e expectedRevision. Revisado set_order_delivery registra o método de entrega visível ao cliente e o transportador opcional, referência e link HTTPS. Estas ferramentas seguem as permissões atuais do membro e o escopo do cliente. Veja Pedidos para os campos e comportamento.