Referencia MCP
Automatizaciones y skills por MCP
Cómo tu asistente redacta una automatización, la prueba y la ejecuta, la enciende (solo cuando está lista) y ejecuta una skill guardada en la nube de Nirvai.
Dos áreas vecinas de la conexión. automations cubre el trabajo que se repite solo — redáctalo,
pruébalo, ejecútalo, enciéndelo. skills cubre un trabajo guardado, ejecutado una vez, cuando lo pides.
Redacta, prueba, ejecuta — y enciende solo cuando está lista
Tu asistente puede instalar un temporizador — elegir la hora, pasar el cable, montar la tapa, e incluso probar que el cableado funciona. También puede subir el interruptor, pero solo en uno que esté de verdad terminado: la conexión se niega a activar una automatización a medio cablear (un disparador al que aún le falta su conexión, un paso que no resuelve) y te dice exactamente qué falta. Crear una nunca la enciende por sí sola — eso sigue siendo un acto deliberado.
| Acción | Alcance | Qué hace |
|---|---|---|
automations.describe_schema | read | La forma que tiene una automatización válida — tipos de disparador, cómo se encadenan los pasos, los dos modos de ejecución. |
automations.templates | read | El catálogo de disparadores reales (un negocio nuevo, una respuesta de formulario, …) y sus payloads de ejemplo. |
automations.validate | read | Comprueba que un diseño es válido antes de crearlo. |
automations.create | create | Redacta la automatización directo en tu cuenta como un borrador inactivo. |
automations.update | write | Edita una automatización que ya tienes. |
automations.test | run | La ejecuta una vez en el momento y devuelve resultados por paso y un enlace a esa ejecución. |
automations.execute | run | La ejecuta de verdad con un payload de entrada que elige tu asistente. |
automations.activate · automations.deactivate | write | La enciende o la apaga. Activar se rechaza hasta que la automatización pueda disparar de verdad. |
automations.runs | read | El historial de ejecuciones, o el detalle por paso de una, para ver qué pasó o por qué falló. |
skills.run | run | Ejecuta una skill guardada en la nube de Nirvai, direccionada por su slug. |
Las automatizaciones son la única área que se salta proponer y luego crear: automations.create
escribe el borrador real (inactivo) en un solo paso. Los nombres viejos automations.propose y
workflows.trigger ya no existen — llamarlos devuelve una nota que apunta a automations.create /
automations.execute.
Qué redacta tu asistente en realidad
Una automatización es un diseño pequeño y explícito: un name, un trigger (manual, cron con
horario y zona horaria, o un evento de app del catálogo de plantillas), los agents que puede usar —
agentes tuyos que ya existen, nombrados por su propio id — y los steps, donde cada uno dice qué
agente corre, qué se le pide, y hacia dónde sigue el flujo si sale bien o si falla. Un execution_mode
opcional elige entre el modo rápido por defecto y el pensado para trabajos largos o pesados.
nirvai_execute(
alias = "automations.create",
args = { name: "Monday pipeline digest",
trigger: { type: "cron", cron: "0 9 * * 1", timezone: "America/Santiago" },
agents: ["sales-analyst"],
steps: [{ node_idx: 1, from_idx: 0, type: "agent", name: "Summarise",
agent: "sales-analyst",
input_prompt: "Summarise last week's closed and stalled deals." }] },
description = "Redactar un resumen de pipeline de los lunes"
)
Archivos y datos de demo
Tu asistente sabe cómo las automatizaciones mueven archivos sin costo — adjuntar un archivo de una base de datos a un correo, guardarlo en un proyecto, publicar una imagen de un proyecto — y siempre completa los datos de demo de la automatización cuando crea una. Para encontrar un archivo de un proyecto, lista tus proyectos con nirvai_list_resources(kind="projects") — cada uno indica si te pertenece, porque solo los proyectos que te pertenecen pueden recibir archivos — y luego los archivos que contiene con projects.list_files.
Dónde la revisas y la ejecutas
automations.create te entrega un enlace a /external/automations/…. A diferencia de las otras
páginas de revisión, esta es en vivo: ves el lienzo, la ejecutas con una entrada, miras las
ejecuciones recientes y — cuando está lista — la enciendes. Cada test y execute también devuelve
un enlace a la ejecución para abrir esa corrida exacta y leer su salida por paso.
- Encenderla está condicionado, no bloqueado. Con un token de alcance
write, tu asistente puede activar una automatización lista; una que aún no lo está se rechaza con el bloqueo exacto (a menudo una conexión que le falta al disparador). Nunca se activa sola al crearla. - Si un disparador necesita un inicio de sesión, tu asistente propone la conexión con los verbos de credenciales y te entrega la página segura — el secreto lo escribes tú. Mira Herramientas y conexiones.
skills.runno involucra ninguna página de revisión; ejecuta una skill que ya tienes y devuelve el resultado.
Skills: un procedimiento guardado, ejecutado en la nube
Una skill es código real que tus agentes ya tienen disponible. skills.run ejecuta exactamente
una de ellas — nombrada por su slug, nunca por su nombre visible — del lado de Nirvai, con una
carpeta de trabajo de verdad debajo. Los archivos que produce se sincronizan de vuelta a tu sesión,
así tu asistente los puede tomar en el paso siguiente.
nirvai_execute(
alias = "skills.run",
args = { skill: "bulk-enrich", module: "main", entry: "run",
args: { table_session: "8e0438a3-…" },
tool_ids: [1697], session: "q3-cleanup" },
description = "Enriquecer las cuentas nuevas del trimestre con el tamaño de empresa"
)
Es el extremo opuesto a un script de datos de una live app, y el contraste es deliberado:
| Script de datos de live app | skills.run | |
|---|---|---|
| Importaciones, archivos, red | Ninguna — datos puros que entran y salen | Un entorno completo, con carpeta de trabajo |
| Puede cambiar tus registros | Nunca | Sí, si las herramientas que recibe lo permiten |
| Qué corre | Código escrito para esa app, revisado línea por línea | Una skill conocida y guardada, traída por su slug |
| Sesión | Obligatoria | Obligatoria — es a quien pertenece la carpeta de trabajo |
Un script de live app está enjaulado a propósito porque es código recién escrito. Una skill no lo
está de la misma manera porque no es nueva — es el mismo procedimiento que tus agentes ya ejecutan, y
no hay forma de entregarle a skills.run código libre en su lugar.
Límites y garantías
- Crear hace un borrador. Una automatización nueva está inactiva;
automations.activatees un acto aparte, y se rechaza hasta que la automatización pueda disparar de verdad. - Solo agentes existentes. Los pasos referencian agentes que ya tienes; uno desconocido se rechaza antes de escribir nada.
- Llamar a create dos veces crea dos. Crear una automatización no es idempotente — una llamada
repetida es una segunda automatización, no una actualización; usa
automations.updatepara cambiarla. - Corre en Nirvai, y queda registrado.
test/executese ejecutan del lado de Nirvai, consumen créditos sin importar quién las redactó, y cada ejecución es direccionable por un enlace en el Feed de Actividad. - Solo skills conocidas.
skills.runrecibe un slug, un módulo y un punto de entrada — no un cuerpo de código, y solo alcanza las herramientas y tablas nombradas en la llamada. - Resultados acotados. La salida vuelve como una vista previa con tope más un archivo descargable. Las ejecuciones largas vuelven como aún corriendo en vez de colgarse en silencio.
- Llaves distintas. Redactar necesita
create; editar, encender/apagar necesitanwrite; probar, ejecutar y las skills necesitanrun. Mira los alcances.