MCP de Nuvia

Los asistentes de IA como Claude y ChatGPT son excelentes para conversar, pero no ven los datos de su empresa. El MCP (Model Context Protocol) es un estándar abierto que tiende ese puente: con el servidor MCP de Nuvia, su asistente pasa a acceder a contactos, listas, conversaciones y campañas de su cuenta como tools que él mismo decide llamar durante la conversación. Usted pide en lenguaje natural, por ejemplo “crea una lista con los leads de tecnología en São Paulo”, y el asistente busca, crea o actualiza la información, sin escribir código. Las tools respetan los permisos y el consumo de créditos de su cuenta, tal como las acciones hechas desde la interfaz.

¿MCP o API REST?

Son dos caminos distintos, para usos distintos:

	MCP	API REST
Para qué	Uso vía asistente de IA, en lenguaje natural	Integración programática (servidores, scripts)
Autenticación	OAuth 2.1 (inicio de sesión + autorización en el cliente)	API key (Bearer), ver Autenticación
Scope	`mcp:tools`	scopes de API key (`agents`, `contacts`, …)

El MCP no usa la API key REST. La autenticación del MCP es OAuth 2.1, con el scope mcp:tools: un sistema separado de los scopes de API key. No intente autenticarse en el MCP con una API key, ni reutilizar aquí los scopes REST.

El servidor MCP de Nuvia está en https://api.nuvia.ai/mcp (transporte Streamable HTTP). Esa es la URL que se agrega como conector en el asistente de IA.

Cómo conectar

Solo los usuarios con perfil Usuario o Admin pueden usar el MCP. El flujo es el mismo en clientes compatibles como claude.ai, Claude Desktop y Cursor:

Agregue el conector

En su asistente de IA, agregue un conector MCP con la URL https://api.nuvia.ai/mcp.

Inicie sesión y autorice

El cliente abre el flujo OAuth de Nuvia. Inicie sesión y haga clic en Autorizar para conceder el acceso.

Comience a usarlo

Pida en lenguaje natural, mencionando el conector de Nuvia cuando sea necesario.

El paso a paso detallado por aplicación (con capturas de pantalla) cambia con frecuencia y está en el artículo oficial: Cómo conectar el MCP de Nuvia.

Herramientas disponibles

Las tools cubren acciones equivalentes a las de la plataforma, organizadas en seis grupos.

Búsqueda

Prospección en la base global y en la base Brasil (CNPJ), y resolución de valores de filtro.

Herramienta	Qué hace
`search_businesses`	Busca empresas en la base global, por tamaño, país, industria, ingresos, tecnología usada, etc.
`search_prospects`	Busca personas/decisores en la base global, por cargo, seniority, ubicación y firmografía.
`search_brazil_companies`	Busca empresas brasileñas en la base de CNPJ, por estado (UF), CNAE, situación registral, tamaño, socio, etc.
`lookup_filter_values`	Resuelve un término libre (ej.: “software”) al valor exacto aceptado por los filtros de la búsqueda global.
`lookup_brazil_filter_values`	Misma función, para los filtros de la base brasileña (CNAE, naturaleza jurídica, ciudad, UF, etc.).
`link_brazil_to_global`	Cruza una empresa brasileña (por el CNPJ) con la base global, para luego buscar a sus decisores.
`link_global_to_brazil`	Camino inverso: a partir del dominio de una empresa global, trae los datos registrales brasileños.

Listas y registros

Gestionar listas de CRM y los registros dentro de ellas.

Herramienta	Qué hace
`list_lists`	Lista las listas de CRM de la empresa, con nombre, tipo (Contacto/Empresa), columnas y cantidad de registros.
`get_list`	Trae metadatos y columnas detalladas de una lista: paso usado antes de agregar o actualizar registros.
`create_list`	Crea una lista, del tipo Contacto o Empresa (el tipo no cambia después de creada). No verifica duplicidad por nombre.
`add_list_column`	Agrega nuevas columnas a una lista existente, preservando las actuales.
`list_records`	Lista los registros (filas) de una lista, organizados por nombre de columna.
`add_records`	Agrega contactos o empresas ya existentes en el CRM a una lista.
`update_record`	Actualiza una fila de la lista, combinando con lo que ya existe (no borra las demás columnas).
`update_records`	Igual al anterior, en lote (hasta 100 filas por llamada).
`save_search_results`	Guarda los resultados de una búsqueda global como contactos/empresas en el CRM, opcionalmente ya en una lista. Asíncrono.
`get_save_status`	Consulta el progreso del guardado hasta que finaliza.

create_list no verifica duplicidad por nombre: pedir crear la misma lista dos veces crea dos listas separadas. Como el pedido en lenguaje natural facilita duplicar sin querer, confirme si la lista ya existe antes de crearla.

Los resultados de búsqueda global no entran directo a una lista: primero materialícelos como registros del CRM con save_search_results, luego refiéralos con add_records.

Contactos

Trabaja con la base de contactos de la cuenta como un todo (no solo dentro de una lista).

Herramienta	Qué hace
`list_contacts`	Lista/busca contactos del CRM, por nombre, correo electrónico o teléfono.
`find_contacts_by_phone`	Resuelve una lista de teléfonos a los contactos correspondientes, útil para verificar duplicidad.
`create_contact`	Crea un contacto (nombre, código de país y teléfono obligatorios; correo, cargo y otros opcionales).
`create_contacts`	Crea contactos en lote (hasta 100 por llamada).
`update_contact`	Actualiza un contacto existente (solo se modifican los campos enviados).
`update_contacts`	Actualiza contactos en lote (hasta 100 por llamada).
`add_contact_note`	Agrega una anotación a un contacto (hasta 5000 caracteres).
`list_contact_notes`	Lista las anotaciones de un contacto, de la más reciente a la más antigua.

Las operaciones en lote no se detienen si un elemento falla: la falla queda aislada y los demás elementos se procesan con normalidad.

Conversaciones

Herramienta	Qué hace
`list_conversations`	Lista las conversaciones de atención al cliente, con contacto, inbox, agente, estado y resumen del último mensaje.
`list_messages`	Lista el contenido de una conversación (texto, tipo, remitente, fecha y adjuntos).

Las tools de Conversaciones son de solo lectura. El envío de mensajes no se expone vía MCP. Para responder o iniciar una conversación, use la plataforma.

Campañas

Herramienta	Qué hace
`list_campaigns`	Lista las campañas de la empresa (las archivadas no aparecen), con estado, canal, métricas y remitentes.
`get_campaign`	Trae los detalles de una campaña: estado, canal, disparador y métricas.

Las tools de Campañas son de solo lectura. Crear, editar o activar campañas se sigue haciendo en la plataforma.

Enriquecimiento

Herramienta	Qué hace
`enrich_list`	Dispara el enriquecimiento de correo electrónico y/o teléfono de los contactos elegibles de una lista, ya sea la lista entera o un recorte (vista/filtros). Asíncrono.
`get_enrich_status`	Consulta el progreso (0 a 100%) del enriquecimiento.

Créditos: buscar y cruzar datos nunca consume crédito. La única tool que consume crédito es enrich_list: correo electrónico = 1 crédito/contacto y teléfono = 10 créditos/contacto. El costo es proporcional a la cantidad de contactos elegibles en el objetivo, que puede ser la lista entera o un recorte (vista/filtros), así que el asistente confirma el tamaño antes de disparar; atención en listas grandes.

Ejemplos de uso

Pida en lenguaje natural. Algunos ejemplos:

“Use el conector de Nuvia para buscar contactos con el cargo ‘Director de Marketing’ en empresas de tecnología en Brasil.”
“Use el conector de Nuvia para crear una lista llamada ‘Leads Enterprise SP’ del tipo Contacto.”
“Use el conector de Nuvia para enriquecer el correo electrónico y el teléfono de los contactos de la lista ‘Leads Enterprise SP’.”

Según el asistente, puede ser necesario repetir “use el conector de Nuvia” en cada solicitud, sobre todo si tiene otros conectores activos con acciones similares.

Solución de problemas

Si el conector aparece inactivo, pida al asistente que llame a la tool whoami. Si la respuesta no llega o no trae el nombre de su empresa, rehaga la autorización (inicio de sesión + Autorizar) en la pantalla del cliente MCP. El paso a paso está en Cómo conectar el MCP de Nuvia.

Auditoría

Todas las llamadas al MCP quedan auditadas. En la plataforma, acceda a Configuración → Auditoría MCP para ver autenticaciones, sesiones y llamadas de herramientas hechas por su empresa.

¿MCP o API REST?

Cómo conectar

Herramientas disponibles

Búsqueda

Listas y registros

Contactos

Conversaciones

Campañas

Enriquecimiento

Ejemplos de uso

Solución de problemas

Auditoría

Próximos pasos

Guía completa del MCP

Secciones de la API

​¿MCP o API REST?

​Cómo conectar

​Herramientas disponibles

​Búsqueda

​Listas y registros

​Contactos

​Conversaciones

​Campañas

​Enriquecimiento

​Ejemplos de uso

​Solución de problemas

​Auditoría

​Próximos pasos

Guía completa del MCP

Secciones de la API

¿MCP o API REST?

Cómo conectar

Herramientas disponibles

Búsqueda

Listas y registros

Contactos

Conversaciones

Campañas

Enriquecimiento

Ejemplos de uso

Solución de problemas

Auditoría

Próximos pasos