MCP: Funnels, stages and tags
Funnels, stages, tags and contact channels through the MCP. 28 tools.
Tools in this area, generated from the server code. The descriptions come from that code, in Portuguese. To connect, see the XBASE MCP.
add-board-stage
Adiciona uma etapa (coluna) a um quadro do workspace. Sem order, entra no fim.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
boardId | yes | ID do quadro (veja list-boards) |
name | yes | — |
description | no | — |
order | no | Posição (0 = primeira) |
add-contact-address
Adiciona um endereço ao contato. Rua, cidade e estado são obrigatórios; isMain torna este o endereço principal (o anterior deixa de ser).
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
nickname | no | Apelido (ex.: Casa, Escritório) |
street | yes | — |
number | no | — |
complement | no | — |
district | no | Bairro |
city | yes | — |
state | yes | — |
country | no | Padrão: Brasil |
zipCode | no | CEP |
obs | no | — |
isMain | no | — |
add-contact-channel
Adiciona um canal ao contato (WhatsApp, e-mail, Instagram…). source é o número, e-mail ou usuário. Não abre conversa: use get-or-create-thread para isso.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
type | yes | — |
source | yes | Número (com DDI), e-mail ou usuário do canal |
isPrimary | no | — |
isVerified | no | — |
add-thread-member-agent
Coloca um agente do workspace como membro da thread (ele passa a acompanhar a conversa) sem trocar o responsável. Para trocar o responsável use change-thread-responsible.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
threadId | yes | ID da thread (veja list-threads) |
agentId | yes | ID do agente (veja get-agents-by-workspace) |
archive-thread
Arquiva uma thread do workspace (sai das listas de conversas abertas; nada é apagado). Use archived=false para desarquivar.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
threadId | yes | ID da thread (veja list-threads) |
archived | no | true (padrão) arquiva; false desarquiva |
create-board
Cria um quadro (funil) no workspace. stages cria as etapas na ordem dada (ex.: ["Novo", "Em negociação", "Ganho"]); depois dá para mexer com add-board-stage, update-board-stage e delete-board-stage.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
name | yes | — |
description | no | — |
status | no | — |
stages | no | Nomes das etapas, na ordem |
delete-board
DESTRUTIVA E SEM VOLTA: exclui em definitivo o quadro e todas as etapas dele; as threads que estavam no funil ficam sem etapa. Confirme com a pessoa antes de usar.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
boardId | yes | ID do quadro (veja list-boards) |
delete-board-stage
DESTRUTIVA E SEM VOLTA: exclui em definitivo uma etapa do quadro; as threads que estavam nela ficam sem etapa. Confirme com a pessoa antes de usar.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
stageId | yes | ID da etapa (veja get-board ou list-workspace-stages) |
delete-contact
DESTRUTIVA: exclui um contato do workspace (some das listas e buscas; o histórico das conversas fica). Confirme com a pessoa antes de usar.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
duplicate-board
Cria um quadro novo usando um quadro do workspace como modelo (copia etapas e configurações, sem as threads). Sem description, herda a do modelo.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
boardId | yes | ID do quadro modelo |
name | yes | Nome do quadro novo |
description | no | — |
get-board
Detalhe de um quadro (funil) do workspace com as etapas em ordem (id, nome, descrição, ordem).
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
boardId | yes | ID do quadro (veja list-boards) |
get-contact-details
Ficha de um contato do workspace: dados básicos, canais ativos (com o id usado em update/remove-contact-channel) e endereços (com o id usado em update/remove-contact-address).
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
get-thread
Detalhe de uma thread (negociação/conversa) do workspace: título, status, etapa do funil, contatos, tags, membros e flags (arquivada, fixada, silenciada). As mensagens ficam em get-thread-dialogs.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
threadId | yes | ID da thread (veja list-threads) |
list-boards
Lista os quadros (funis) do workspace com as etapas de cada um, em ordem.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
take | no | Quantidade (padrão 50) |
skip | no | — |
list-organizations
Lista as organizações (empresas) do CRM do workspace, das atualizadas mais recentemente para as mais antigas, com paginação. Para buscar por nome/CNPJ/domínio use search-organizations.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
take | no | Quantidade (padrão 20, máximo 100) |
skip | no | Quantas pular (paginação) |
remove-contact-address
DESTRUTIVA: apaga em definitivo um endereço do contato (não há lixeira).
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
addressId | yes | ID do endereço |
remove-contact-channel
DESTRUTIVA: remove um canal do contato (o número/e-mail deixa de aparecer na ficha). Se era o telefone ou e-mail principal, o contato passa a usar outro canal do mesmo tipo, se houver.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
channelId | yes | ID do canal |
search-contacts
Lista/busca contatos do workspace com paginação. search procura em nome, e-mail e telefone (sem diferenciar maiúsculas). Devolve id, nome, e-mail, telefone e organização de cada contato.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
search | no | Termo em nome, e-mail ou telefone |
organizationId | no | Só contatos desta organização |
take | no | Quantidade (padrão 20, máximo 100) |
skip | no | Quantos pular (paginação) |
update-board
Edita nome, descrição ou status de um quadro do workspace. Para as etapas use add-board-stage, update-board-stage e delete-board-stage.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
boardId | yes | ID do quadro (veja list-boards) |
name | no | — |
description | no | — |
status | no | — |
update-board-stage
Renomeia, muda a descrição ou a posição (order) de uma etapa de um quadro do workspace.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
stageId | yes | ID da etapa (veja get-board ou list-workspace-stages) |
name | no | — |
description | no | — |
order | no | — |
update-contact-address
Edita um endereço do contato. Só os campos enviados mudam; isMain torna este o principal.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
addressId | yes | ID do endereço |
nickname | no | — |
street | no | — |
number | no | — |
complement | no | — |
district | no | — |
city | no | — |
state | no | — |
country | no | — |
zipCode | no | — |
obs | no | — |
isMain | no | — |
update-contact-channel
Edita um canal do contato: tipo, origem (número/e-mail/usuário), principal, verificado ou ativo. Só os campos enviados mudam.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
contactId | yes | ID do contato (veja search-contacts) |
channelId | yes | ID do canal (veja get-contact-details) |
type | no | — |
source | no | — |
isPrimary | no | — |
isVerified | no | — |
isActive | no | — |
update-thread
Edita uma thread do workspace: título, status, etapa do funil (boardStageId de um quadro deste workspace), fixar, silenciar, favoritar, marcar alerta (redFlag) ou arquivar. Só os campos enviados mudam.
| Parameter | Required | Description |
|---|---|---|
workspaceId | no | Opcional: só é aceito se for o workspace do token (o workspace vem sempre da credencial) |
threadId | yes | ID da thread (veja list-threads) |
title | no | — |
status | no | — |
boardStageId | no | ID da etapa (veja get-board ou list-workspace-stages) |
isPinned | no | — |
isMuted | no | — |
isFavorite | no | — |
redFlag | no | — |
isArchived | no | — |
list-workspace-stages
Lista os stages (etapas) de um workspace, com o ID de cada um e o quadro a que pertence. Pode filtrar por quadro (boardId). Use antes de move-thread-to-stage para pegar o boardStageId exato (nomes se repetem entre quadros).
| Parameter | Required | Description |
|---|---|---|
workspaceId | yes | ID do workspace para listar stages |
boardId | no | ID do quadro para filtrar stages (opcional) |
move-thread-to-stage
Move a thread para uma etapa (stage) do quadro. PREFIRA boardStageId (ID exato, obtido em list-workspace-stages): nomes se repetem entre quadros. Com stageName, procura primeiro no quadro atual da thread e depois nos outros quadros do mesmo workspace (nunca em outro workspace); se houver mais de uma etapa com o nome, devolve as opções com ID para você escolher. A etapa precisa ser do mesmo workspace da thread.
| Parameter | Required | Description |
|---|---|---|
threadId | yes | ID da thread a ser movida |
boardStageId | no | ID exato da etapa de destino (preferido). Se vier junto com stageName, vale o boardStageId |
stageName | no | Nome da etapa de destino (usado quando não houver boardStageId) |
add-tag-to-entity
Adiciona tag a entidade (thread, agent, contact, rawContact). Cria tag automaticamente se não existir. Use para organização.
| Parameter | Required | Description |
|---|---|---|
entityType | yes | Tipo da entidade (thread, agent, contact, rawContact) |
entityId | yes | ID da entidade |
tagName | yes | Nome da tag a ser adicionada |
tagColor | no | Cor da tag em formato hex (ex: #FF5733) |
createTagIfNotExists | no | Se deve criar a tag caso não exista (padrão: true) |
create-tag
Cadastra uma tag no catálogo do workspace sem etiquetar nada (para etiquetar use add-tag-to-entity). Se já existir uma tag com o mesmo nome no workspace, devolve a existente. Devolve o id da tag.
| Parameter | Required | Description |
|---|---|---|
name | yes | Nome da tag (ex.: "awb_nao_encontrado") |
color | no | Cor em hex (padrão #64748b) |
workspaceId | no | Opcional: precisa ser o workspace do token |
remove-tag-from-entity
Remove tag de entidade específica. Verifica existência da associação antes de remover. Use para limpeza de tags.
| Parameter | Required | Description |
|---|---|---|
entityType | yes | Tipo da entidade (thread, agent, contact, rawContact) |
entityId | yes | ID da entidade |
tagName | no | Nome da tag a ser removida (alternativa ao tagId) |
tagId | no | ID da tag a ser removida (alternativa ao tagName) |