> ## Documentation Index > Fetch the complete documentation index at: https://developers.nuvia.ai/llms.txt > Use this file to discover all available pages before exploring further. # MCP da Nuvia > Conecte assistentes de IA (Claude, ChatGPT, Cursor) aos dados da sua empresa na Nuvia via MCP 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](/autenticacao) | | 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**: No seu assistente de IA, adicione um conector MCP com a URL `https://api.nuvia.ai/mcp`. O cliente abre o fluxo OAuth da Nuvia. Faça login e clique em **Autorizar** para conceder o acesso. 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](https://docs.nuvia.ai/pt-BR/articles/15422389-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](https://docs.nuvia.ai/pt-BR/articles/15422389-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. ## Próximos passos Artigo oficial com todos os detalhes e exemplos de uso. Para integração programática via API Key, veja o mapa de domínios.