O servidor MCP da Nuvia expõe um conjunto de ferramentas que permitem a um assistente de IA (como Claude, ChatGPT ou um agente próprio) buscar dados de mercado, ler e escrever no seu CRM, acompanhar conversas e campanhas — tudo dentro dos dados da sua empresa. Esta página lista todas as ferramentas disponíveis hoje, o que cada uma faz e seus principais argumentos.
Módulo: MCP da Nuvia (acessado por um assistente de IA compatível com MCP)
Antes de começar
Para usar estas ferramentas, você precisa primeiro conectar um assistente de IA ao MCP da Nuvia. Veja Como conectar o MCP da Nuvia. Para acompanhar tudo o que foi executado via MCP, veja Como usar a Auditoria MCP.
Três conceitos valem para todas as ferramentas:
-
Leitura x Escrita — ferramentas de Leitura apenas consultam dados; ferramentas de Escrita criam ou alteram registros. A tabela de cada seção indica o tipo.
-
Restrito à sua empresa — todas as ferramentas de CRM operam apenas sobre os dados da empresa autenticada no token. Uma ferramenta nunca acessa dados de outra empresa.
-
Créditos — buscar e cruzar bases é gratuito. A única ferramenta que consome créditos é o enriquecimento (
enrich_list). Todas as demais não têm custo em créditos.
Identidade da sessão
| Ferramenta | Tipo | O que faz |
|---|---|---|
whoami |
Leitura | Retorna a identidade autenticada na sessão MCP atual: ids e nomes do usuário e da empresa. |
Busca e cruzamento de bases
Ferramentas de descoberta na base global (Explorium) e na base brasileira de CNPJ. Todas são gratuitas. Os filtros de categoria, localização e cargo só aceitam valores de catálogo — por isso, resolva o termo do usuário com uma ferramenta de lookup_* antes de buscar (a exceção é o cargo em search_prospects, que aceita texto livre).
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
search_businesses |
Leitura | Busca empresas na base global por filtros firmográficos (foco fora do Brasil). | filters (ex.: country_code, company_size, naics_category), page, page_size |
search_prospects |
Leitura | Descobre pessoas/decisores novos na base global. Não enriquece quem já está no CRM — para isso use enrich_list. |
filters (job_title aceita texto livre, job_level, job_department, country_code), page, page_size |
search_brazil_companies |
Leitura | Busca empresas brasileiras na base nacional de CNPJ. | filters (ex.: uf, cnae_principal, situacao_cadastral), filter_operator (and/or), page, page_size |
lookup_filter_values |
Leitura | Resolve um termo livre nos valores válidos de um filtro de search_businesses/search_prospects. Chame antes de buscar por categoria/localização/cargo. |
field, query, entity_type (businesses ou prospects) |
lookup_brazil_filter_values |
Leitura | Resolve um termo livre nos valores válidos de um filtro de search_brazil_companies (CNAE, natureza jurídica, cidade, etc.). |
field, query |
link_brazil_to_global |
Leitura | Vincula uma empresa brasileira (CNPJ) à base global, devolvendo o business_id global — útil para prospectar decisores e enriquecer com dados globais. |
cnpj, domain?, company_name? |
link_global_to_brazil |
Leitura | Vincula uma empresa global à base brasileira pelo domínio, devolvendo CNPJ, razão social, sócios, situação cadastral e CNAE. | domain |
Salvar resultados de busca no CRM
Os resultados de search_* são globais e temporários. Estas ferramentas os materializam como contatos e empresas dentro do seu CRM.
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
save_search_results |
Escrita | Salva resultados de uma busca (prospects, businesses ou empresas BR) como registros do CRM, opcionalmente adicionando-os a uma lista. É assíncrona: enfileira um job e devolve job_id. |
result_type, ids (até 2000), save_mode (contacts ou list), list_id?/list_name? |
get_save_status |
Leitura | Consulta o status de um save disparado por save_search_results, com as contagens de contatos e empresas criados/atualizados. O status expira após alguns minutos. |
job_id |
Contatos
Leitura e escrita de contatos no seu CRM (registros nativos da Nuvia).
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
list_contacts |
Leitura | Lista e busca contatos já cadastrados na empresa. search cobre nome, e-mail e telefone. Notas e atributos customizados são omitidos. |
search?, filters?, page, page_size (≤20) |
find_contacts_by_phone |
Leitura | Reconcilia uma lista de telefones com contatos já cadastrados, normalizando DDI e máscara antes do match. | phones (até 50) |
create_contact |
Escrita | Cria um contato. Obrigatórios: name, country_code, phone_number. |
name, country_code, phone_number, opcionais (email, job_title, additional_attributes, etc.) |
create_contacts |
Escrita | Cria vários contatos numa única chamada (até 100), com falha parcial isolada por item. | contacts (lista) |
update_contact |
Escrita | Atualiza um contato. Só os campos enviados mudam; additional_attributes faz merge (não substitui). |
id, campos a alterar |
update_contacts |
Escrita | Atualiza vários contatos numa única chamada (até 100), com falha parcial isolada por item. | updates (lista) |
add_contact_note |
Escrita | Adiciona uma anotação a um contato. O autor é o usuário autenticado. | contact_id, content (até 5000 caracteres) |
list_contact_notes |
Leitura | Lista as anotações de um contato, das mais recentes para as mais antigas. | contact_id |
Listas
Listas agrupam contatos ou empresas com colunas próprias, reutilizáveis em campanhas e funis.
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
list_lists |
Leitura | Lista as listas de CRM da empresa, com nome, tipo, status e contagem de linhas. | search?, object_type?, page, page_size |
get_list |
Leitura | Retorna os metadados de uma lista, incluindo as colunas (key, name, type, source). Use antes de adicionar ou atualizar registros. | id |
create_list |
Escrita | Cria uma lista que agrupa contatos ou empresas (o tipo é imutável após a criação). | name, object_type, description?, columns? |
add_list_column |
Escrita | Adiciona uma ou mais colunas a uma lista existente (até 20), preservando as atuais. | list_id, columns |
Registros (linhas de lista)
Cada registro é uma linha de uma lista, ligada a exatamente um contato ou uma empresa.
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
list_records |
Leitura | Lista as linhas de uma lista num formato plano por nome de coluna. Use get_list antes para conhecer as colunas. |
table_id, filters?, sort?, page, page_size |
add_records |
Escrita | Adiciona registros a uma lista (até 100). Idempotente: linhas já presentes voltam em skipped. |
table_id, records (cada um com contact_id ou business_id) |
update_record |
Escrita | Atualiza uma linha, fazendo merge por chave de coluna (não apaga as demais). | row_id, data |
update_records |
Escrita | Atualiza várias linhas numa única chamada (até 100), com falha parcial isolada. | updates (lista) |
Enriquecimento
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
enrich_list |
Escrita | Preenche campos faltantes (e-mail, telefone) de contatos que já existem em uma lista. É assíncrona: enfileira o lote e devolve jobId, estimatedCredits e contactCount. |
list_id, fields (email/phone_number), view_id?, filters? |
get_enrich_status |
Leitura | Consulta o status de um enriquecimento. Gratuita. Jobs concluídos saem da fila (aí retornam status “unknown”). | job_id |
Conversas
Leitura das conversas de atendimento e suas mensagens.
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
list_conversations |
Leitura | Lista conversas de atendimento. Cada item traz contato, inbox, agente, status e o último resumo de mensagem. | search?, status? (OPEN/RESOLVED), channel?, page, page_size |
list_messages |
Leitura | Lista as mensagens de uma conversa, das mais recentes para as mais antigas, com conteúdo, quem enviou, status e anexos. | conversation_id, page, page_size |
Campanhas
Leitura das campanhas de prospecção da empresa e criação/ativação de campanhas.
| Ferramenta | Tipo | O que faz | Argumentos principais |
|---|---|---|---|
list_campaigns |
Leitura | Lista campanhas da empresa (arquivadas são omitidas). Cada item traz nome, status, canal, tipo de gatilho, métricas e remetentes. | search?, status?, page, page_size |
get_campaign |
Leitura | Detalha uma campanha específica, incluindo suas métricas. | id |
create_campaign |
Escrita | Cria uma campanha na sua empresa. Ela nasce sempre em rascunho — nunca é ativada nem envia mensagens. Já monta a audiência (os contatos entram na campanha) e devolve o total de contatos incluídos. | name, channel_type, trigger_type, audience_config |
activate_campaign |
Escrita | Ativa uma campanha em rascunho, colocando-a no ar, e coloca os envios na fila na hora. Exige confirmação explícita. | campaign_id, confirmed |
Criar uma campanha pelo assistente de IA
A create_campaign monta a campanha com as mesmas regras da plataforma e a deixa em rascunho, para você revisar e ativar depois. Informe:
-
name— nome da campanha -
channel_type— canal de envio (WhatsApp, LinkedIn ou multicanal) -
trigger_type— como a campanha é acionada (manual, agendada, recorrente ou por gatilho externo) -
audience_config— quem entra na campanha: uma ou mais listas, um funil (com etapa opcional), uma seleção estática de contatos ou critérios de audiência dinâmica
As mesmas validações da tela valem aqui: o remetente precisa ser da sua empresa e do canal escolhido, campanhas com gatilho externo exigem audiência do tipo externo, e listas e funis informados precisam pertencer à sua empresa — caso contrário a criação é recusada com o motivo do erro.
A audiência já entra montada. Ao criar a campanha, a ferramenta também inclui os contatos na campanha e devolve quantos entraram. Isso vale para audiências de lista, funil e seleção estática. Audiências dinâmicas e de gatilho externo funcionam diferente por natureza: os contatos entram depois, conforme o gatilho acontece — então o total começa em zero, e isso é o esperado.
Se algo falhar depois que a campanha já foi criada, a resposta sempre traz o nome e o id do rascunho — use esses dados para encontrá-la na plataforma e retomar de onde parou, em vez de criar outra.
Ativar uma campanha pelo assistente de IA
Para a ativação funcionar, a campanha precisa estar pronta e em estado ativável:
-
Ter ao menos uma etapa com Funil Inteligente ativo
-
Não estar arquivada, já ativa nem ser uma campanha manual já concluída
Se algum desses pontos falhar, a ferramenta devolve o motivo e a campanha continua como está.
Os envios entram na fila na hora. Ao ativar, a ferramenta já coloca os contatos da audiência na fila de envio e devolve quantos foram enfileirados — o mesmo que acontece quando você ativa pela tela. Antes era preciso esperar o processamento automático seguinte para os disparos começarem.
Se a ativação der certo mas o enfileiramento falhar, a resposta avisa explicitamente que a campanha está ativa, mas os envios não foram enfileirados, e traz o id dela. Nesse caso, dispare ou reative pela plataforma.
Agent Builder — criar e editar Funis Inteligentes
Além dos dados e do CRM, o MCP da Nuvia expõe o Agent Builder: ferramentas para ler, testar e — para administradores — criar e editar Funis Inteligentes conversando com a IA, sem clicar tela por tela. Para o passo a passo, veja Como criar e editar Funis Inteligentes pelo MCP (Agent Builder).
Leitura e simulação (qualquer usuário)
| Ferramenta | Tipo | O que faz |
|---|---|---|
builder_list_agents |
Leitura | Lista os agentes (Funis Inteligentes) da empresa. |
builder_get_agent |
Leitura | Abre a configuração completa de um agente. |
builder_list_agent_flows |
Leitura | Lista os funis e suas etapas. |
builder_list_teams |
Leitura | Lista os times da empresa. |
builder_list_users |
Leitura | Lista os usuários da empresa. |
builder_list_skills |
Leitura | Lista as habilidades reutilizáveis disponíveis. |
builder_get_skill |
Leitura | Abre os detalhes de uma habilidade reutilizável. |
builder_list_custom_fields |
Leitura | Lista os campos personalizados. |
builder_list_integrations |
Leitura | Lista as integrações conectadas na empresa. |
builder_list_businesses |
Leitura | Lista as empresas (registros) da conta. |
builder_agent_quality_stats |
Leitura | Mostra a taxa de qualificação de um agente num período (padrão 60 dias). Use como piso comparativo, não como número exato. |
builder_simulate_conversation |
Leitura | Ensaia uma conversa com o agente (até 10 mensagens) sem falar com o lead nem criar conversa real. Não executa habilidades externas. |
builder_hubspot_get_settings |
Leitura | Lê a configuração atual da integração com o HubSpot. |
builder_hubspot_list_pipelines |
Leitura | Lista os funis (pipelines) de Deals do HubSpot. |
builder_hubspot_list_owners |
Leitura | Lista os responsáveis (owners) do HubSpot. |
builder_hubspot_list_properties |
Leitura | Lista as propriedades do HubSpot. |
Criação e edição (apenas Company Admin)
| Ferramenta | Tipo | O que faz |
|---|---|---|
builder_push_agent |
Escrita | Cria ou reescreve um agente — sempre como rascunho, nunca ativando nada sozinho. Roda a verificação de qualidade. |
builder_edit_agent |
Escrita | Edita um agente existente, preservando as ações e transições já publicadas e mantendo o status (editar um agente ativo não o tira do ar). Se o agente estiver ativo, exige confirmação explícita antes de alterar qualquer coisa. |
builder_dump_agent |
Escrita | Exporta um funil inteiro (agentes, etapas, follow-ups, campos, tabelas, habilidades e mídia) num arquivo válido por 24h. |
builder_load_agent |
Escrita | Recria, dentro da própria empresa, um funil exportado, reconectando tudo automaticamente. |
builder_create_custom_field |
Escrita | Cria um campo personalizado. Por conversa, aceita apenas os tipos texto, data e número. |
builder_hubspot_set_field_mappings |
Escrita | Define o mapeamento de campos entre Nuvia e HubSpot. |
builder_hubspot_set_deal_stage_mappings |
Escrita | Define o mapeamento de etapas do funil para estágios de Deal do HubSpot. |
builder_hubspot_set_owner_mappings |
Escrita | Define o mapeamento de responsáveis (owners). |
builder_hubspot_set_sync_settings |
Escrita | Define as regras de sincronização (criar contato automaticamente, modelo de nome, origem do dono, etc.). |