MCP da Nuvia

Assistentes de IA como o Claude e o ChatGPT são ótimos para conversar, mas não enxergam os dados da sua empresa. O MCP (Model Context Protocol) é um padrão aberto que faz essa ponte: com o servidor MCP da Nuvia, o seu assistente passa a acessar contatos, listas, conversas e campanhas da sua conta como tools que ele mesmo decide chamar durante a conversa. Você pede em linguagem natural — por exemplo, “crie uma lista com os leads de tecnologia em São Paulo” — e ele busca, cria ou atualiza a informação para você, sem escrever código. As tools respeitam as permissões e o consumo de créditos da sua conta, exatamente como as ações feitas pela interface.

MCP ou API REST?

São dois caminhos diferentes, para usos diferentes:

	MCP	API REST
Para quê	Uso via assistente de IA, em linguagem natural	Integração programática (servidores, scripts)
Autenticação	OAuth 2.1 (login + autorização no cliente)	API Key (Bearer) — veja Autenticação
Escopo	`mcp:tools`	escopos de API Key (`agents`, `contacts`, …)

O MCP não usa a API Key REST. A autenticação do MCP é OAuth 2.1, com o escopo mcp:tools — um sistema separado dos escopos de API Key. Não tente autenticar no MCP com uma API Key, nem reaproveitar os escopos REST aqui.

O servidor MCP da Nuvia fica em https://api.nuvia.ai/mcp (transporte Streamable HTTP) — essa é a URL que você adiciona como conector no seu assistente de IA.

Como conectar

Apenas usuários com perfil Usuário ou Admin podem usar o MCP. O fluxo é o mesmo em clientes compatíveis como claude.ai, Claude Desktop e Cursor:

Adicione o conector

No seu assistente de IA, adicione um conector MCP com a URL https://api.nuvia.ai/mcp.

Faça login e autorize

O cliente abre o fluxo OAuth da Nuvia. Faça login e clique em Autorizar para conceder o acesso.

Comece a usar

Peça em linguagem natural, mencionando o conector da Nuvia quando necessário.

O passo a passo detalhado por aplicativo (com telas) muda com frequência e está no artigo oficial: Como conectar o MCP da Nuvia.

Ferramentas disponíveis

As tools cobrem ações equivalentes às da plataforma, organizadas em seis grupos.

Busca

Prospecção na base global e na base Brasil (CNPJ), e resolução de valores de filtro.

Ferramenta	O que faz
`search_businesses`	Busca empresas na base global, por porte, país, indústria, receita, tecnologia usada, etc.
`search_prospects`	Busca pessoas/decisores na base global, por cargo, senioridade, localização e firmografia.
`search_brazil_companies`	Busca empresas brasileiras na base de CNPJ, por UF, CNAE, situação cadastral, porte, sócio, etc.
`lookup_filter_values`	Resolve um termo livre (ex.: “software”) no valor exato aceito pelos filtros da busca global.
`lookup_brazil_filter_values`	Mesma função, para os filtros da base brasileira (CNAE, natureza jurídica, cidade, UF, etc.).
`link_brazil_to_global`	Cruza uma empresa brasileira (pelo CNPJ) com a base global, para depois buscar seus decisores.
`link_global_to_brazil`	Caminho inverso: a partir do domínio de uma empresa global, traz os dados cadastrais brasileiros.

Listas e registros

Gerenciar listas de CRM e os registros dentro delas.

Ferramenta	O que faz
`list_lists`	Lista as listas de CRM da empresa, com nome, tipo (Contato/Empresa), colunas e quantidade de registros.
`get_list`	Traz metadados e colunas detalhadas de uma lista — passo usado antes de adicionar ou atualizar registros.
`create_list`	Cria uma lista, do tipo Contato ou Empresa (o tipo não muda depois de criada). Não verifica duplicidade por nome.
`add_list_column`	Adiciona novas colunas a uma lista existente, preservando as atuais.
`list_records`	Lista os registros (linhas) de uma lista, organizados por nome de coluna.
`add_records`	Adiciona contatos ou empresas já existentes no CRM a uma lista.
`update_record`	Atualiza uma linha da lista, mesclando com o que já existe (não apaga as demais colunas).
`update_records`	Igual ao anterior, em lote (até 100 linhas por chamada).
`save_search_results`	Salva os resultados de uma busca global como contatos/empresas no CRM, opcionalmente já em uma lista. Assíncrono.
`get_save_status`	Consulta o andamento do salvamento até concluir.

create_list não verifica duplicidade por nome: pedir para criar a mesma lista duas vezes cria duas listas separadas. Como o pedido em linguagem natural facilita duplicar sem querer, confirme se a lista já existe antes de criar.

Resultados de busca global não entram direto em uma lista: primeiro materialize-os como registros do CRM com save_search_results, depois referencie-os com add_records.

Contatos

Trabalha com a base de contatos da conta como um todo (não apenas dentro de uma lista).

Ferramenta	O que faz
`list_contacts`	Lista/busca contatos do CRM, por nome, e-mail ou telefone.
`find_contacts_by_phone`	Resolve uma lista de telefones para os contatos correspondentes — útil para checar duplicidade.
`create_contact`	Cria um contato (nome, DDI e telefone obrigatórios; e-mail, cargo e outros opcionais).
`create_contacts`	Cria contatos em lote (até 100 por chamada).
`update_contact`	Atualiza um contato existente (só os campos enviados são alterados).
`update_contacts`	Atualiza contatos em lote (até 100 por chamada).
`add_contact_note`	Adiciona uma anotação a um contato (até 5000 caracteres).
`list_contact_notes`	Lista as anotações de um contato, da mais recente para a mais antiga.

Operações em lote não travam se um item falhar: a falha fica isolada e os demais itens são processados normalmente.

Conversas

Ferramenta	O que faz
`list_conversations`	Lista as conversas de atendimento, com contato, inbox, agente, status e resumo da última mensagem.
`list_messages`	Lista o conteúdo de uma conversa (texto, tipo, remetente, data e anexos).

As tools de Conversas são somente leitura. O envio de mensagens não é exposto via MCP — para responder ou disparar uma conversa, use a plataforma.

Campanhas

Ferramenta	O que faz
`list_campaigns`	Lista as campanhas da empresa (arquivadas não aparecem), com status, canal, métricas e remetentes.
`get_campaign`	Traz os detalhes de uma campanha: status, canal, gatilho e métricas.

As tools de Campanhas são somente leitura. Criar, editar ou disparar campanhas continua sendo feito na plataforma.

Enriquecimento

Ferramenta	O que faz
`enrich_list`	Dispara o enriquecimento de e-mail e/ou telefone dos contatos elegíveis de uma lista — a lista inteira ou um recorte (view/filtros). Assíncrono.
`get_enrich_status`	Consulta o andamento (0 a 100%) do enriquecimento.

Créditos: buscar e cruzar dados nunca consome crédito. A única tool que consome crédito é enrich_list: e-mail = 1 crédito/contato e telefone = 10 créditos/contato. O custo é proporcional ao número de contatos elegíveis no alvo — que pode ser a lista inteira ou um recorte (view/filtros) —, então o assistente confirma o tamanho antes de disparar; atenção em listas grandes.

Exemplos de uso

Peça em linguagem natural. Alguns exemplos:

“Utilize o conector da Nuvia para buscar contatos com o cargo ‘Diretor de Marketing’ em empresas de tecnologia no Brasil.”
“Utilize o conector da Nuvia para criar uma lista chamada ‘Leads Enterprise SP’ do tipo Contato.”
“Utilize o conector da Nuvia para enriquecer o e-mail e o telefone dos contatos da lista ‘Leads Enterprise SP’.”

Dependendo do assistente, pode ser necessário repetir “utilize o conector da Nuvia” a cada solicitação — sobretudo se você tiver outros conectores ativos com ações parecidas.

Solução de problemas

Se o conector aparecer inativo, peça ao assistente para chamar a tool whoami. Se a resposta não vier ou não trouxer o nome da sua empresa, refaça a autorização (login + Autorizar) na tela do cliente MCP. O passo a passo está em Como conectar o MCP da Nuvia.

Auditoria

Todas as chamadas ao MCP são auditadas. Na plataforma, acesse Configurações → Auditoria MCP para ver autenticações, sessões e chamadas de ferramentas feitas pela sua empresa.

MCP ou API REST?

Como conectar

Ferramentas disponíveis

Busca

Listas e registros

Contatos

Conversas

Campanhas

Enriquecimento

Exemplos de uso

Solução de problemas

Auditoria

Próximos passos

Guia completo do MCP

Seções da API

​MCP ou API REST?

​Como conectar

​Ferramentas disponíveis

​Busca

​Listas e registros

​Contatos

​Conversas

​Campanhas

​Enriquecimento

​Exemplos de uso

​Solução de problemas

​Auditoria

​Próximos passos

Guia completo do MCP

Seções da API

MCP ou API REST?

Como conectar

Ferramentas disponíveis

Busca

Listas e registros

Contatos

Conversas

Campanhas

Enriquecimento

Exemplos de uso

Solução de problemas

Auditoria

Próximos passos