El servidor MCP de Nuvia expone un conjunto de herramientas que permiten a un asistente de IA (como Claude, ChatGPT o un agente propio) buscar datos de mercado, leer y escribir en tu CRM, y seguir conversaciones y campañas — todo dentro de los datos de tu empresa. Esta página enumera todas las herramientas disponibles hoy, qué hace cada una y sus principales argumentos.
Disponible en: cuentas con acceso al MCP de Nuvia.
Quién puede hacerlo: cualquier asistente de IA autenticado en el MCP de Nuvia (perfiles Usuario y Company Admin).
Módulo: MCP de Nuvia (al que se accede con un asistente de IA compatible con MCP)
Antes de empezar
Para usar estas herramientas, primero necesitas conectar un asistente de IA al MCP de Nuvia. Consulta Cómo conectar el MCP de Nuvia. Para seguir todo lo que se ejecutó por MCP, consulta Cómo usar la Auditoría MCP.
Tres conceptos valen para todas las herramientas:
-
Lectura vs. Escritura — las herramientas de Lectura solo consultan datos; las de Escritura crean o modifican registros. La tabla de cada sección indica el tipo.
-
Restringido a tu empresa — todas las herramientas de CRM operan solo sobre los datos de la empresa autenticada en el token. Una herramienta nunca accede a datos de otra empresa.
-
Créditos — buscar y cruzar bases es gratuito. La única herramienta que consume créditos es el enriquecimiento (
enrich_list). Todas las demás no tienen costo en créditos.
Identidad de la sesión
| Herramienta | Tipo | Qué hace |
|---|---|---|
whoami |
Lectura | Devuelve la identidad autenticada en la sesión MCP actual: ID y nombres del usuario y de la empresa. |
Búsqueda y cruce de bases
Herramientas de descubrimiento en la base global (Explorium) y en la base brasileña de CNPJ. Todas son gratuitas. Los filtros de categoría, ubicación y cargo solo aceptan valores del catálogo — por eso, resuelve el término del usuario con una herramienta lookup_* antes de buscar (la excepción es el cargo en search_prospects, que acepta texto libre).
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
search_businesses |
Lectura | Busca empresas en la base global por filtros firmográficos (enfoque fuera de Brasil). | filters (por ej.: country_code, company_size, naics_category), page, page_size |
search_prospects |
Lectura | Descubre personas/tomadores de decisión nuevos en la base global. No enriquece a quien ya está en el CRM — para eso usa enrich_list. |
filters (job_title acepta texto libre, job_level, job_department, country_code), page, page_size |
search_brazil_companies |
Lectura | Busca empresas brasileñas en la base nacional de CNPJ. | filters (por ej.: uf, cnae_principal, situacao_cadastral), filter_operator (and/or), page, page_size |
lookup_filter_values |
Lectura | Resuelve un término libre en los valores válidos de un filtro de search_businesses/search_prospects. Llámala antes de buscar por categoría/ubicación/cargo. |
field, query, entity_type (businesses o prospects) |
lookup_brazil_filter_values |
Lectura | Resuelve un término libre en los valores válidos de un filtro de search_brazil_companies (CNAE, naturaleza jurídica, ciudad, etc.). |
field, query |
link_brazil_to_global |
Lectura | Vincula una empresa brasileña (CNPJ) a la base global y devuelve el business_id global — útil para prospectar tomadores de decisión y enriquecer con datos globales. |
cnpj, domain?, company_name? |
link_global_to_brazil |
Lectura | Vincula una empresa global a la base brasileña por el dominio y devuelve CNPJ, razón social, socios, situación registral y CNAE. | domain |
Guardar resultados de búsqueda en el CRM
Los resultados de search_* son globales y temporales. Estas herramientas los convierten en contactos y empresas dentro de tu CRM.
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
save_search_results |
Escritura | Guarda los resultados de una búsqueda (prospects, businesses o empresas de Brasil) como registros del CRM y, opcionalmente, los agrega a una lista. Es asíncrona: pone un job en cola y devuelve job_id. |
result_type, ids (hasta 2000), save_mode (contacts o list), list_id?/list_name? |
get_save_status |
Lectura | Consulta el estado de un guardado disparado por save_search_results, con los conteos de contactos y empresas creados/actualizados. El estado vence después de algunos minutos. |
job_id |
Contactos
Lectura y escritura de contactos en tu CRM (registros nativos de Nuvia).
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
list_contacts |
Lectura | Lista y busca contactos ya registrados en la empresa. search cubre nombre, correo electrónico y teléfono. Las notas y los atributos personalizados se omiten. |
search?, filters?, page, page_size (≤20) |
find_contacts_by_phone |
Lectura | Concilia una lista de teléfonos con contactos ya registrados, normalizando el código de país y el formato antes de la coincidencia. | phones (hasta 50) |
create_contact |
Escritura | Crea un contacto. Obligatorios: name, country_code, phone_number. |
name, country_code, phone_number, opcionales (email, job_title, additional_attributes, etc.) |
create_contacts |
Escritura | Crea varios contactos en una sola llamada (hasta 100), con fallas parciales aisladas por ítem. | contacts (lista) |
update_contact |
Escritura | Actualiza un contacto. Solo cambian los campos enviados; additional_attributes se combina (no se reemplaza). |
id, campos a modificar |
update_contacts |
Escritura | Actualiza varios contactos en una sola llamada (hasta 100), con fallas parciales aisladas por ítem. | updates (lista) |
add_contact_note |
Escritura | Agrega una nota a un contacto. El autor es el usuario autenticado. | contact_id, content (hasta 5000 caracteres) |
list_contact_notes |
Lectura | Lista las notas de un contacto, de las más recientes a las más antiguas. | contact_id |
Listas
Las listas agrupan contactos o empresas con columnas propias, reutilizables en campañas y embudos.
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
list_lists |
Lectura | Lista las listas de CRM de la empresa, con nombre, tipo, estado y cantidad de filas. | search?, object_type?, page, page_size |
get_list |
Lectura | Devuelve los metadatos de una lista, incluidas las columnas (key, name, type, source). Úsala antes de agregar o actualizar registros. | id |
create_list |
Escritura | Crea una lista que agrupa contactos o empresas (el tipo no se puede cambiar después de crearla). | name, object_type, description?, columns? |
add_list_column |
Escritura | Agrega una o más columnas a una lista existente (hasta 20), conservando las actuales. | list_id, columns |
Registros (filas de lista)
Cada registro es una fila de una lista, vinculada exactamente a un contacto o a una empresa.
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
list_records |
Lectura | Lista las filas de una lista en un formato plano por nombre de columna. Usa get_list antes para conocer las columnas. |
table_id, filters?, sort?, page, page_size |
add_records |
Escritura | Agrega registros a una lista (hasta 100). Idempotente: las filas que ya están vuelven en skipped. |
table_id, records (cada uno con contact_id o business_id) |
update_record |
Escritura | Actualiza una fila, combinando por clave de columna (no borra las demás). | row_id, data |
update_records |
Escritura | Actualiza varias filas en una sola llamada (hasta 100), con fallas parciales aisladas. | updates (lista) |
Enriquecimiento
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
enrich_list |
Escritura | Completa campos faltantes (correo electrónico, teléfono) de contactos que ya existen en una lista. Es asíncrona: pone el lote en cola y devuelve jobId, estimatedCredits y contactCount. |
list_id, fields (email/phone_number), view_id?, filters? |
get_enrich_status |
Lectura | Consulta el estado de un enriquecimiento. Gratuita. Los jobs terminados salen de la cola (entonces devuelven el estado “unknown”). | job_id |
Conversaciones
Lectura de las conversaciones de atención y sus mensajes.
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
list_conversations |
Lectura | Lista conversaciones de atención. Cada ítem trae contacto, inbox, agente, estado y el resumen del último mensaje. | search?, status? (OPEN/RESOLVED), channel?, page, page_size |
list_messages |
Lectura | Lista los mensajes de una conversación, de los más recientes a los más antiguos, con contenido, remitente, estado y adjuntos. | conversation_id, page, page_size |
Campañas
Lectura de las campañas de prospección de la empresa y creación/activación de campañas.
| Herramienta | Tipo | Qué hace | Argumentos principales |
|---|---|---|---|
list_campaigns |
Lectura | Lista las campañas de la empresa (las archivadas se omiten). Cada ítem trae nombre, estado, canal, tipo de disparador, métricas y remitentes. | search?, status?, page, page_size |
get_campaign |
Lectura | Detalla una campaña específica, incluidas sus métricas. | id |
create_campaign |
Escritura | Crea una campaña en tu empresa. Siempre nace como borrador — nunca se activa ni envía mensajes. Ya arma la audiencia (los contactos entran en la campaña) y devuelve el total de contactos incluidos. | name, channel_type, trigger_type, audience_config |
activate_campaign |
Escritura | Activa una campaña en borrador, la pone en el aire y pone los envíos en cola al instante. Exige confirmación explícita. | campaign_id, confirmed |
Crear una campaña desde el asistente de IA
create_campaign arma la campaña con las mismas reglas de la plataforma y la deja como borrador, para que la revises y la actives después. Indica:
-
name— nombre de la campaña -
channel_type— canal de envío (WhatsApp, LinkedIn o multicanal) -
trigger_type— cómo se activa la campaña (manual, programada, recurrente o por disparador externo) -
audience_config— quién entra en la campaña: una o más listas, un embudo (con etapa opcional), una selección estática de contactos o criterios de audiencia dinámica
Las mismas validaciones de la pantalla valen aquí: el remitente tiene que ser de tu empresa y del canal elegido, las campañas con disparador externo exigen una audiencia de tipo externo, y las listas y embudos indicados tienen que pertenecer a tu empresa — de lo contrario, la creación se rechaza con el motivo del error.
La audiencia ya entra armada. Al crear la campaña, la herramienta también incluye los contactos en la campaña y devuelve cuántos entraron. Esto vale para audiencias de lista, embudo y selección estática. Las audiencias dinámicas y de disparador externo funcionan distinto por naturaleza: los contactos entran después, a medida que ocurre el disparador — por eso el total empieza en cero, y eso es lo esperado.
Si algo falla después de que la campaña ya se creó, la respuesta siempre trae el nombre y el ID del borrador — usa esos datos para encontrarla en la plataforma y retomar desde donde quedó, en lugar de crear otra.
Activar una campaña desde el asistente de IA
Para que la activación funcione, la campaña tiene que estar lista y en un estado que permita activarla:
-
Tener al menos una etapa con un Embudo Inteligente activo
-
No estar archivada, ya activa ni ser una campaña manual ya concluida
Si alguno de estos puntos falla, la herramienta devuelve el motivo y la campaña queda como está.
Los envíos entran en la cola al instante. Al activar, la herramienta ya pone los contactos de la audiencia en la cola de envío y devuelve cuántos se pusieron en cola — lo mismo que pasa cuando activas desde la pantalla. Antes había que esperar el siguiente procesamiento automático para que empezaran los envíos.
Si la activación funciona pero la puesta en cola falla, la respuesta avisa explícitamente que la campaña está activa, pero los envíos no se pusieron en cola, y trae su ID. En ese caso, dispárala o reactívala desde la plataforma.
Agent Builder — crear y editar Embudos Inteligentes
Además de los datos y del CRM, el MCP de Nuvia expone el Agent Builder: herramientas para leer, probar y — si eres administrador — crear y editar Embudos Inteligentes conversando con la IA, sin hacer clic pantalla por pantalla. Para el paso a paso, consulta Cómo crear y editar Embudos Inteligentes por el MCP (Agent Builder).
Lectura y simulación (cualquier usuario)
| Herramienta | Tipo | Qué hace |
|---|---|---|
builder_list_agents |
Lectura | Lista los agentes (Embudos Inteligentes) de la empresa. |
builder_get_agent |
Lectura | Abre la configuración completa de un agente. |
builder_list_agent_flows |
Lectura | Lista los embudos y sus etapas. |
builder_list_teams |
Lectura | Lista los equipos de la empresa. |
builder_list_users |
Lectura | Lista los usuarios de la empresa. |
builder_list_skills |
Lectura | Lista las habilidades reutilizables disponibles. |
builder_get_skill |
Lectura | Abre los detalles de una habilidad reutilizable. |
builder_list_custom_fields |
Lectura | Lista los campos personalizados. |
builder_list_integrations |
Lectura | Lista las integraciones conectadas en la empresa. |
builder_list_businesses |
Lectura | Lista las empresas (registros) de la cuenta. |
builder_agent_quality_stats |
Lectura | Muestra la tasa de calificación de un agente en un período (por defecto 60 días). Úsala como piso comparativo, no como un número exacto. |
builder_simulate_conversation |
Lectura | Ensaya una conversación con el agente (hasta 10 mensajes) sin hablar con el lead ni crear una conversación real. No ejecuta habilidades externas. |
builder_hubspot_get_settings |
Lectura | Lee la configuración actual de la integración con HubSpot. |
builder_hubspot_list_pipelines |
Lectura | Lista los pipelines de Deals de HubSpot. |
builder_hubspot_list_owners |
Lectura | Lista los responsables (owners) de HubSpot. |
builder_hubspot_list_properties |
Lectura | Lista las propiedades de HubSpot. |
Creación y edición (solo Company Admin)
| Herramienta | Tipo | Qué hace |
|---|---|---|
builder_push_agent |
Escritura | Crea o reescribe un agente — siempre como borrador, sin activar nada por su cuenta. Ejecuta la verificación de calidad. |
builder_edit_agent |
Escritura | Edita un agente existente, conservando las acciones y transiciones ya publicadas y manteniendo el estado (editar un agente activo no lo saca del aire). Si el agente está activo, exige confirmación explícita antes de cambiar cualquier cosa. |
builder_dump_agent |
Escritura | Exporta un embudo completo (agentes, etapas, seguimientos, campos, tablas, habilidades y multimedia) en un archivo válido por 24 h. |
builder_load_agent |
Escritura | Recrea, dentro de la propia empresa, un embudo exportado, reconectando todo automáticamente. |
builder_create_custom_field |
Escritura | Crea un campo personalizado. Desde la conversación, acepta solo los tipos texto, fecha y número. |
builder_hubspot_set_field_mappings |
Escritura | Define el mapeo de campos entre Nuvia y HubSpot. |
builder_hubspot_set_deal_stage_mappings |
Escritura | Define el mapeo de las etapas del embudo a las etapas de Deal de HubSpot. |
builder_hubspot_set_owner_mappings |
Escritura | Define el mapeo de responsables (owners). |
builder_hubspot_set_sync_settings |
Escritura | Define las reglas de sincronización (crear el contacto automáticamente, modelo de nombre, origen del dueño, etc.). |