1. [Ayuda](https://nuvia.ai/es/docs) 2. [MCP de Nuvia](https://nuvia.ai/es/docs/colecoes/19724087-mcp-de-nuvia) # Referencia de las herramientas MCP de Nuvia Lista completa de las herramientas del MCP: búsqueda, CRM, listas, enriquecimiento, conversaciones y campañas — qué hace cada una y sus 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) Actualizado el 3 de noviembre de 2026 [MCP de Nuvia](https://nuvia.ai/es/docs/colecoes/19724087-mcp-de-nuvia) 1. [Cómo conectar el MCP de Nuvia](https://nuvia.ai/es/docs/artigos/15422389-como-conectar-el-mcp-de-nuvia) 2. [Cómo crear y editar Embudos Inteligentes por el MCP (Agent Builder)](https://nuvia.ai/es/docs/artigos/16074655-crear-editar-embudos-inteligentes-mcp-agent-builder) 3. [Referencia de las herramientas MCP de Nuvia](https://nuvia.ai/es/docs/artigos/16074574-referencia-herramientas-mcp-de-nuvia) 4. [Cómo usar la Auditoría MCP](https://nuvia.ai/es/docs/artigos/15422393-como-usar-la-auditoria-mcp) 5. [Cómo conectar el MCP de Nuvia a Google Antigravity](https://nuvia.ai/es/docs/artigos/16530912-conectar-mcp-de-nuvia-a-google-antigravity) 6. [Cómo conectar el MCP de Nuvia en Microsoft Copilot Studio](https://nuvia.ai/es/docs/artigos/17765183-como-conectar-mcp-de-nuvia-en-microsoft-copilot-studio) En esta página 1. Antes de empezar 2. Identidad de la sesión 3. Búsqueda y cruce de bases 4. Guardar resultados de búsqueda en el CRM 5. Contactos 6. Listas 7. Registros (filas de lista) 8. Enriquecimiento 9. Conversaciones 10. Campañas 11. Agent Builder — crear y editar Embudos Inteligentes 12. Preguntas frecuentes **En esta página12 secciones** 1. Antes de empezar 2. Identidad de la sesión 3. Búsqueda y cruce de bases 4. Guardar resultados de búsqueda en el CRM 5. Contactos 6. Listas 7. Registros (filas de lista) 8. Enriquecimiento 9. Conversaciones 10. Campañas 11. Agent Builder — crear y editar Embudos Inteligentes 12. Preguntas frecuentes 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](https://nuvia.ai/es/docs/artigos/15422389-como-conectar-el-mcp-de-nuvia). Para seguir todo lo que se ejecutó por MCP, consulta [Cómo usar la Auditoría MCP](https://nuvia.ai/es/docs/artigos/15422393-como-usar-la-auditoria-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. Nota Los nombres de las herramientas (por ej.: list_contacts) aparecen exactamente así para el asistente de IA. Rara vez los escribes a mano — normalmente pides en lenguaje natural (por ej.: “lista mis contactos”) y el cliente elige la herramienta correcta. ## Identidad de la sesión HerramientaTipoQué 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). HerramientaTipoQué haceArgumentos 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 Nota country_code en search_businesses filtra por la **sede registrada** (HQ) de la empresa, no por el país donde opera. Para empresas que operan en Brasil (incluidas filiales de multinacionales), usa search_brazil_companies. ## 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. HerramientaTipoQué haceArgumentos 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). HerramientaTipoQué haceArgumentos 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 Importante La creación de contactos no elimina duplicados automáticamente. Usa list_contacts o find_contacts_by_phone antes de crear para evitar registros repetidos. ## Listas Las listas agrupan contactos o empresas con columnas propias, reutilizables en campañas y embudos. HerramientaTipoQué haceArgumentos 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 Importante create_list no elimina duplicados por nombre — llamarla de nuevo con el mismo nombre crea otra lista. Confirma antes de crear. ## Registros (filas de lista) Cada registro es una fila de una lista, vinculada exactamente a un contacto o a una empresa. HerramientaTipoQué haceArgumentos 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) Importante Al editar una columna que refleja un campo del contacto (correo electrónico o teléfono), el cambio **también actualiza el contacto subyacente**. No cambia a qué contacto o empresa está vinculada la fila. ## Enriquecimiento HerramientaTipoQué haceArgumentos 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 Crítico enrich_list es la **única** herramienta que consume créditos — **1 crédito por correo electrónico** y **10 créditos por teléfono**, por contacto — y se ejecuta sobre todos los contactos elegibles de la selección. Verifica el tamaño de la lista con get_list y confirma antes de dispararla, sobre todo en listas grandes. El consumo no se puede deshacer. ## Conversaciones Lectura de las conversaciones de atención y sus mensajes. HerramientaTipoQué haceArgumentos 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 **Novedad — origen de anuncio (Click-to-WhatsApp):** Cuando la conversación nació de un anuncio Click-to-WhatsApp, list_conversations también devuelve un objeto referral con el ID del anuncio (source_id), tipo, app de origen, URL, ctwa_clid, fuente de conversión y título. Esto permite atribuir conversaciones a las campañas de anuncios que las generaron, directamente desde el asistente de IA. ## Campañas Lectura de las campañas de prospección de la empresa y creación/activación de campañas. HerramientaTipoQué haceArgumentos 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. Límite de audiencia por MCP las audiencias con **más de 1.000 contactos** no se arman aquí — la campaña se crea como **borrador** y la respuesta trae su nombre y su ID, con el aviso para que armes la audiencia y la actives **desde la plataforma**. Los volúmenes grandes tardan demasiado para caber en una respuesta del asistente de IA; en la pantalla esto se ejecuta en segundo plano, con barra de progreso. 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 Crítico Activar una campaña la pone **en el aire** y **envía mensajes reales** a los leads de la audiencia. Por eso activate_campaign tiene una protección: sin la confirmación explícita (confirmed), **no activa** — devuelve un pedido para que el asistente de IA lo confirme contigo antes. Confirma solo cuando estés seguro de que la campaña puede empezar a enviar ahora. 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)](https://nuvia.ai/es/docs/artigos/16074655-crear-editar-embudos-inteligentes-mcp-agent-builder). Importante Las herramientas del Agent Builder aparecen con el prefijo builder_ y solo están disponibles cuando el **Agent Builder MCP está habilitado para la empresa** (activado por defecto). Las herramientas de **lectura y simulación** valen para cualquier usuario; las de **creación y edición** son exclusivas del perfil **Company Admin**. ### Lectura y simulación (cualquier usuario) HerramientaTipoQué 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) HerramientaTipoQué 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.). Nota Publicar un agente por el MCP siempre crea un **borrador** que pasa por la verificación de calidad — activar sigue siendo una acción consciente que haces tú. La exportación/importación de embudos por el Company Admin queda **dentro de la propia cuenta**. ## Preguntas frecuentes ## Preguntas frecuentes **¿Necesito saber los nombres de las herramientas para usar el MCP?** No. Conversas con el MCP en lenguaje natural (por ej.: “¿qué campañas están activas?”) y él elige la herramienta correcta. Esta referencia te sirve para entender qué es posible hacer y a qué datos accede cada acción. **¿Alguna de estas herramientas consume créditos?** Solo el enriquecimiento (enrich_list): 1 crédito por correo electrónico y 10 por teléfono, por contacto. Buscar, cruzar bases, leer y escribir en el CRM y ver conversaciones y campañas no consumen créditos. **¿El MCP puede acceder a datos de otra empresa?** No. Todas las herramientas de CRM están restringidas a la empresa autenticada en el token de la sesión. Una herramienta devuelve un error si intentas acceder a un registro que no pertenece a tu empresa. **¿Por qué algunas búsquedas vuelven vacías aunque el término sea correcto?** Los filtros de categoría, ubicación y cargo (excepto el cargo en search_prospects) solo aceptan valores del catálogo. Resuelve el término con lookup_filter_values (base global) o lookup_brazil_filter_values (base brasileña) antes de buscar y usa el valor devuelto. **¿Las herramientas de enriquecimiento y de guardar búsqueda responden al instante?** No. enrich_list y save_search_results son asíncronas: ponen un job en cola y devuelven un identificador. Usa get_enrich_status o get_save_status con ese ID para seguirlo. Los jobs terminados salen de la cola, así que un estado “unknown” normalmente significa que el procesamiento ya terminó. **¿Quién puede crear o editar agentes por el MCP?** Leer y simular agentes vale para cualquier usuario de la empresa (con el Agent Builder habilitado, que es lo predeterminado). Crear, editar, exportar e importar agentes, además de configurar HubSpot, son exclusivos del perfil **Company Admin**. **¿Un cambio hecho por la IA sale al aire automáticamente?** No. Publicar un agente por el MCP siempre crea un **borrador**, que pasa por la verificación de calidad. La activación sigue siendo una acción consciente que haces tú. **¿Puedo auditar lo que se hizo por el MCP?** Sí. La Auditoría MCP registra autenticaciones, sesiones y llamadas a herramientas. Consulta [Cómo usar la Auditoría MCP](https://nuvia.ai/es/docs/artigos/15422393-como-usar-la-auditoria-mcp). [AnteriorCómo crear y editar Embudos Inteligentes por el MCP (Agent Builder)](https://nuvia.ai/es/docs/artigos/16074655-crear-editar-embudos-inteligentes-mcp-agent-builder) [SiguienteCómo usar la Auditoría MCP](https://nuvia.ai/es/docs/artigos/15422393-como-usar-la-auditoria-mcp) ¿Te ayudó este artículo? ## Artículos relacionados - [Cómo conectar el MCP de Nuvia](https://nuvia.ai/es/docs/artigos/15422389-como-conectar-el-mcp-de-nuvia) - [Cómo conectar el MCP de Nuvia a Google Antigravity](https://nuvia.ai/es/docs/artigos/16530912-conectar-mcp-de-nuvia-a-google-antigravity) [MCP de Nuvia](https://nuvia.ai/es/docs/colecoes/19724087-mcp-de-nuvia) 1. [Cómo conectar el MCP de Nuvia](https://nuvia.ai/es/docs/artigos/15422389-como-conectar-el-mcp-de-nuvia) 2. [Cómo crear y editar Embudos Inteligentes por el MCP (Agent Builder)](https://nuvia.ai/es/docs/artigos/16074655-crear-editar-embudos-inteligentes-mcp-agent-builder) 3. [Referencia de las herramientas MCP de Nuvia](https://nuvia.ai/es/docs/artigos/16074574-referencia-herramientas-mcp-de-nuvia) 4. [Cómo usar la Auditoría MCP](https://nuvia.ai/es/docs/artigos/15422393-como-usar-la-auditoria-mcp) 5. [Cómo conectar el MCP de Nuvia a Google Antigravity](https://nuvia.ai/es/docs/artigos/16530912-conectar-mcp-de-nuvia-a-google-antigravity) 6. [Cómo conectar el MCP de Nuvia en Microsoft Copilot Studio](https://nuvia.ai/es/docs/artigos/17765183-como-conectar-mcp-de-nuvia-en-microsoft-copilot-studio) ## ¿Todavía necesitas ayuda? Los clientes hablan con soporte por el chat dentro de la plataforma. ¿Aún no eres cliente? Habla con nuestro equipo. [Hablar con soporte en la plataforma](https://app.nuvia.ai) [Aún no soy cliente](https://nuvia.ai/es/contact) --- Source: https://nuvia.ai/es/docs/artigos/16074574-referencia-herramientas-mcp-de-nuvia