1. [Ajuda](https://nuvia.ai/docs) 2. [MCP da Nuvia](https://nuvia.ai/docs/colecoes/19724087-mcp-da-nuvia) # Referência das ferramentas MCP da Nuvia Lista completa das ferramentas do MCP: busca, CRM, listas, enriquecimento, conversas e campanhas — o que cada uma faz e seus argumentos. Disponível em contas com acesso ao MCP da Nuvia Quem pode fazer qualquer assistente de IA autenticado no MCP da Nuvia (perfis Usuário e Company Admin ) Atualizado em 3 de novembro de 2026 [MCP da Nuvia](https://nuvia.ai/docs/colecoes/19724087-mcp-da-nuvia) 1. [Como utilizar o MCP da Nuvia](https://nuvia.ai/docs/artigos/15825545-como-utilizar-o-mcp-da-nuvia) 2. [Como conectar o MCP da Nuvia](https://nuvia.ai/docs/artigos/15422389-como-conectar-o-mcp-da-nuvia) 3. [Como criar e editar Funis Inteligentes pelo MCP (Agent Builder)](https://nuvia.ai/docs/artigos/16074655-como-criar-e-editar-funis-inteligentes-pelo-mcp-agent-builder) 4. [Referência das ferramentas MCP da Nuvia](https://nuvia.ai/docs/artigos/16074574-referencia-das-ferramentas-mcp-da-nuvia) 5. [Como usar a Auditoria MCP](https://nuvia.ai/docs/artigos/15422393-como-usar-a-auditoria-mcp) 6. [Como conectar o MCP da Nuvia ao Google Antigravity](https://nuvia.ai/docs/artigos/16530912-como-conectar-o-mcp-da-nuvia-ao-google-antigravity) 7. [Como conectar o MCP da Nuvia no Microsoft Copilot Studio](https://nuvia.ai/docs/artigos/17765183-como-conectar-o-mcp-da-nuvia-no-microsoft-copilot-studio) Nesta página 1. Antes de começar 2. Identidade da sessão 3. Busca e cruzamento de bases 4. Salvar resultados de busca no CRM 5. Contatos 6. Listas 7. Registros (linhas de lista) 8. Enriquecimento 9. Conversas 10. Campanhas 11. Agent Builder — criar e editar Funis Inteligentes **Nesta página11 seções** 1. Antes de começar 2. Identidade da sessão 3. Busca e cruzamento de bases 4. Salvar resultados de busca no CRM 5. Contatos 6. Listas 7. Registros (linhas de lista) 8. Enriquecimento 9. Conversas 10. Campanhas 11. Agent Builder — criar e editar Funis Inteligentes 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](https://nuvia.ai/docs/artigos/15422389-como-conectar-o-mcp-da-nuvia). Para acompanhar tudo o que foi executado via MCP, veja [Como usar a Auditoria MCP](https://nuvia.ai/docs/artigos/15422393-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. Nota Os nomes das ferramentas (ex.: list_contacts) aparecem exatamente assim para o assistente de IA. Você raramente os digita à mão — normalmente pede em linguagem natural (ex.: “liste meus contatos”) e o cliente escolhe a ferramenta certa. ## Identidade da sessão FerramentaTipoO 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). FerramentaTipoO que fazArgumentos 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 Nota country_code em search_businesses filtra pela **sede registrada** (HQ) da empresa, não pelo país de operação. Para empresas que operam no Brasil (incluindo subsidiárias de multinacionais), use search_brazil_companies. ## 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. FerramentaTipoO que fazArgumentos 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). FerramentaTipoO que fazArgumentos 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 Importante A criação de contatos não deduplica automaticamente. Use list_contacts ou find_contacts_by_phone antes de criar para evitar registros repetidos. ## Listas Listas agrupam contatos ou empresas com colunas próprias, reutilizáveis em campanhas e funis. FerramentaTipoO que fazArgumentos 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 Importante create_list não deduplica por nome — chamar de novo com o mesmo nome cria outra lista. Confirme antes de criar. ## Registros (linhas de lista) Cada registro é uma linha de uma lista, ligada a exatamente um contato ou uma empresa. FerramentaTipoO que fazArgumentos 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) Importante Ao editar uma coluna que espelha um campo do contato (e-mail ou telefone), a alteração **também atualiza o contato subjacente**. Não altera a que contato ou empresa a linha está ligada. ## Enriquecimento FerramentaTipoO que fazArgumentos 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 Crítico enrich_list é a **única** ferramenta que consome créditos — **1 crédito por e-mail** e **10 créditos por telefone**, por contato — e roda sobre todos os contatos elegíveis do recorte. Confira o tamanho da lista com get_list e confirme antes de disparar, principalmente em listas grandes. O consumo não pode ser desfeito. ## Conversas Leitura das conversas de atendimento e suas mensagens. FerramentaTipoO que fazArgumentos 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 **Novidade — origem de anúncio (Click-to-WhatsApp):** Quando a conversa nasceu de um anúncio Click-to-WhatsApp, o list_conversations devolve também um objeto referral com o id do anúncio (source_id), tipo, app de origem, URL, ctwa_clid, fonte de conversão e título. Isso permite atribuir conversas às campanhas de anúncio que as geraram, direto pelo assistente de IA. ## Campanhas Leitura das campanhas de prospecção da empresa e criação/ativação de campanhas. FerramentaTipoO que fazArgumentos 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. Limite de audiência pelo MCP audiências com **mais de 1.000 contatos** não são montadas aqui — a campanha é criada como **rascunho** e a resposta traz o nome e o id dela, com o aviso para você montar a audiência e ativar **pela plataforma**. Volumes grandes levam tempo demais para caber em uma resposta do assistente de IA; na tela isso roda em segundo plano, com barra de progresso. 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 Crítico Ativar uma campanha coloca ela **no ar** e **envia mensagens reais** para os leads da audiência. Por isso a activate_campaign tem uma trava: sem a confirmação explícita (confirmed), ela **não ativa** — devolve um pedido para o assistente de IA confirmar com você antes. Confirme só quando tiver certeza de que a campanha pode disparar agora. 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)](https://nuvia.ai/docs/artigos/16074655-como-criar-e-editar-funis-inteligentes-pelo-mcp-agent-builder). Importante As ferramentas do Agent Builder aparecem com o prefixo builder_ e só ficam disponíveis quando o **Agent Builder MCP está habilitado para a empresa** (ligado por padrão). As ferramentas de **leitura e simulação** valem para qualquer usuário; as de **criação e edição** são exclusivas do perfil **Company Admin**. ### Leitura e simulação (qualquer usuário) FerramentaTipoO 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) FerramentaTipoO 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.). Nota Publicar um agente pelo MCP cria sempre um **rascunho** que passa pela verificação de qualidade — ativar continua sendo uma ação consciente, feita por você. A exportação/importação de funil pelo Company Admin fica **dentro da própria conta**. ## Perguntas frequentes **Preciso saber os nomes das ferramentas para usar o MCP?** Não. Você conversa com o MCP em linguagem natural (ex.: “quais campanhas estão ativas?”) e ele escolhe a ferramenta certa. Esta referência serve para você entender o que é possível fazer e quais dados cada ação acessa. **Alguma dessas ferramentas consome créditos?** Apenas o enriquecimento (enrich_list): 1 crédito por e-mail e 10 por telefone, por contato. Buscar, cruzar bases, ler e escrever no CRM, ver conversas e campanhas não consomem créditos. **O MCP pode acessar dados de outra empresa?** Não. Todas as ferramentas de CRM são restritas à empresa autenticada no token da sessão. Uma ferramenta retorna erro se você tentar acessar um registro que não pertence à sua empresa. **Por que algumas buscas voltam vazias mesmo com o termo certo?** Os filtros de categoria, localização e cargo (exceto o cargo em search_prospects) só aceitam valores de catálogo. Resolva o termo com lookup_filter_values (base global) ou lookup_brazil_filter_values (base brasileira) antes de buscar e use o valor retornado. **As ferramentas de enriquecimento e de salvar busca respondem na hora?** Não. enrich_list e save_search_results são assíncronas: elas enfileiram um job e devolvem um identificador. Use get_enrich_status ou get_save_status com esse id para acompanhar. Jobs concluídos saem da fila, então um status “unknown” normalmente significa que o processamento já terminou. **Quem pode criar ou editar agentes pelo MCP?** Ler e simular agentes vale para qualquer usuário da empresa (com o Agent Builder habilitado, o que é padrão). Criar, editar, exportar e importar agentes, além de configurar o HubSpot, são exclusivos do perfil **Company Admin**. **Uma alteração feita pela IA vai ao ar automaticamente?** Não. Publicar um agente pelo MCP cria sempre um **rascunho**, que passa pela verificação de qualidade. A ativação continua sendo uma ação consciente feita por você. **Posso auditar o que foi feito pelo MCP?** Sim. A Auditoria MCP registra autenticações, sessões e chamadas de ferramentas. Veja [Como usar a Auditoria MCP](https://nuvia.ai/docs/artigos/15422393-como-usar-a-auditoria-mcp). [AnteriorComo criar e editar Funis Inteligentes pelo MCP (Agent Builder)](https://nuvia.ai/docs/artigos/16074655-como-criar-e-editar-funis-inteligentes-pelo-mcp-agent-builder) [PróximoComo usar a Auditoria MCP](https://nuvia.ai/docs/artigos/15422393-como-usar-a-auditoria-mcp) Este artigo ajudou? ## Artigos relacionados - [Como conectar o MCP da Nuvia](https://nuvia.ai/docs/artigos/15422389-como-conectar-o-mcp-da-nuvia) - [Como utilizar o MCP da Nuvia](https://nuvia.ai/docs/artigos/15825545-como-utilizar-o-mcp-da-nuvia) - [Como conectar o MCP da Nuvia ao Google Antigravity](https://nuvia.ai/docs/artigos/16530912-como-conectar-o-mcp-da-nuvia-ao-google-antigravity) [MCP da Nuvia](https://nuvia.ai/docs/colecoes/19724087-mcp-da-nuvia) 1. [Como utilizar o MCP da Nuvia](https://nuvia.ai/docs/artigos/15825545-como-utilizar-o-mcp-da-nuvia) 2. [Como conectar o MCP da Nuvia](https://nuvia.ai/docs/artigos/15422389-como-conectar-o-mcp-da-nuvia) 3. [Como criar e editar Funis Inteligentes pelo MCP (Agent Builder)](https://nuvia.ai/docs/artigos/16074655-como-criar-e-editar-funis-inteligentes-pelo-mcp-agent-builder) 4. [Referência das ferramentas MCP da Nuvia](https://nuvia.ai/docs/artigos/16074574-referencia-das-ferramentas-mcp-da-nuvia) 5. [Como usar a Auditoria MCP](https://nuvia.ai/docs/artigos/15422393-como-usar-a-auditoria-mcp) 6. [Como conectar o MCP da Nuvia ao Google Antigravity](https://nuvia.ai/docs/artigos/16530912-como-conectar-o-mcp-da-nuvia-ao-google-antigravity) 7. [Como conectar o MCP da Nuvia no Microsoft Copilot Studio](https://nuvia.ai/docs/artigos/17765183-como-conectar-o-mcp-da-nuvia-no-microsoft-copilot-studio) ## Ainda precisa de ajuda? Clientes falam com o suporte pelo chat dentro da plataforma. Ainda não é cliente? Fale com o nosso time. [Falar com o suporte na plataforma](https://app.nuvia.ai) [Ainda não sou cliente](https://nuvia.ai/contact) --- Source: https://nuvia.ai/docs/artigos/16074574-referencia-das-ferramentas-mcp-da-nuvia