Referencia MCP
Referencia MCP
Toda la superficie de acciones que tu asistente puede llamar por MCP — las herramientas maestras, la gramática de alias, los permisos, las sesiones y cómo vuelven los resultados.
Una vez conectado, tu asistente obtiene algo así como un control remoto universal para Nirvai — un conjunto pequeño y consistente de botones que alcanzan cada parte de tu cuenta: proyectos, bases de datos, herramientas y conexiones, agentes, live apps, automatizaciones y búsqueda web. Esta página describe el contrato observable: las herramientas que ve tu asistente, las acciones que puede nombrar, qué devuelve cada una y las reglas que la conexión aplica antes de que algo se ejecute.
No necesitas memorizar nada de esto — tu asistente descarga esta misma referencia cuando la necesita, y los comandos de barra inician los pasos correctos por ti. Léela cuando quieras saber exactamente qué es capaz de hacer tu asistente, o por qué hizo algo.
Las herramientas maestras
Tu asistente nunca ve cientos de herramientas separadas. Ve un conjunto corto y fijo, y todo lo demás es un argumento de una de ellas.
Piensa en una biblioteca. No tienes una puerta por libro — tienes un catálogo (encontrar algo), una signatura (nombrar el ejemplar exacto), una mesa de lectura (usarlo), una ficha de préstamo (qué sacaste hoy) y una fotocopiadora (meter y sacar páginas). Unas pocas puertas, y una biblioteca entera detrás.
| Herramienta | Qué hace |
|---|---|
nirvai_execute | El único verbo de acción. Toda capacidad pasa por él: nirvai_execute(alias, args, description). |
nirvai_list_resources | "¿Qué tengo?" — lista tus cosas de un tipo dado, cada una con un id estable. |
nirvai_describe | "¿Qué es exactamente esta?" — el contrato en vivo de un solo elemento. |
nirvai_create_session | Abre una ejecución con nombre por adelantado, para que las acciones siguientes la nombren por id. |
nirvai_list_sessions | Lista tus ejecuciones recientes, para que tu asistente retome una. |
nirvai_get_session | Relee una ejecución: qué pasó y los archivos que produjo. |
nirvai_transfer_file | Mueve archivos entre la máquina de tu asistente y Nirvai. |
nirvai_download_skill_package | Descarga las instrucciones de un área (bases de datos, agentes, …) cuando hacen falta. |
nirvai_sync_session | Mantiene una carpeta de trabajo al día — listar, bajar, subir. |
Los asistentes empeoran a medida que crece su lista de herramientas — la elección se vuelve ruidosa. Un verbo con una acción nombrada mantiene el menú corto y el razonamiento afilado, y significa que una capacidad nueva de Nirvai funciona en tu asistente de inmediato, sin que actualices nada.
La gramática de alias
Toda acción es un nombre de dos partes: área.acción.
nirvai_execute(
alias = "db.select",
args = { table_session: "…", condition: "WHERE status = 'Open' LIMIT 50" },
description = "Check which deals are still open"
)
El área decide qué parte de Nirvai responde, cómo se enlaza el resultado y qué permiso hace falta. Estas son las áreas:
| Área | Qué vive ahí | Referencia |
|---|---|---|
projects | Hechos, personas y decisiones a largo plazo | Proyectos |
db | Tus registros, tablas y espacios | Bases de datos |
tools · credentials | Tus herramientas y conexiones guardadas | Herramientas y conexiones |
agents | Construir y ejecutar tus agentes | Agentes |
live_apps | Tableros interactivos sobre tus datos | Live apps |
automations · skills | Trabajo programado y reutilizable | Automatizaciones y skills |
Dos áreas se renombraron: memory → projects, y workflows → automations. Los nombres viejos
están obsoletos — llamar a uno devuelve un error que apunta al nombre nuevo y le pide a tu
asistente volver a descargar el paquete de habilidades de esa área.
| web · media · docs | Búsqueda, imágenes, documentación oficial | Web, medios y documentación |
description nunca es opcional
Cada acción lleva un "por qué" corto y humano. Es lo que convierte el Feed de Actividad en algo que de verdad puedes leer — "Check which deals are still open" en vez de "db.select". Si alguna vez sientes que tu asistente actúa de forma opaca, el feed es donde mirar.
Permisos: cuatro niveles
El token que creas lleva permisos (scopes), y la conexión los verifica antes de decidir siquiera qué significa la acción. Es la diferencia entre un carnet de biblioteca que te deja leer y uno que te deja reordenar los estantes.
| Permiso | Permite | ¿Necesita tu aprobación? |
|---|---|---|
read | Mirar cualquier cosa — listar, describir, recordar, consultar | No |
run | Usar algo que ya existe — ejecutar una herramienta, un agente, probar un script | No |
write | Cambiar algo que existe | Los cambios se aplican directo |
create | Crear algo nuevo | Crear pasa por una página de revisión |
| destructive | Borrar | No se puede otorgar. Se rechaza para todos los tokens. |
Borrar es deliberadamente imposible por la conexión. Si un asistente te dice que borró algo en Nirvai, no lo hizo.
Nada se crea a tus espaldas — la página de revisión
Para cualquier cosa que cree algo real — una conexión, una herramienta, una base de datos, un agente, una live app — tu asistente no lo construye. Lo propone, y te entrega un enlace a una página de revisión dentro de Nirvai con un único botón de Crear/Conectar. Ves exactamente qué se va a crear, puedes cambiarlo, y nada existe hasta que haces clic.
Esto es lo más importante que hay que entender de la conexión, así que aquí está de punta a punta:
De esa forma se desprenden tres cosas:
- Tu asistente nunca conoce tu secreto. Propone "aquí va una clave de API"; la clave la escribes tú en la propia página de Nirvai. El valor nunca toca al asistente, ni al resultado, ni al feed.
- Puedes editar antes de confirmar. La página es un formulario de verdad, no un recibo — cambia el tipo de una columna, renombra una tabla, quita una herramienta que no quieres, y recién ahí haz clic.
- No se puede hacer clic dos veces. Una vez creado, volver a abrirla muestra Creado ✓ y se niega a hacer una segunda copia. Tu asistente se entera del id nuevo por el feed, no proponiendo de nuevo.
Así se ve una conexión propuesta cuando abres su página de revisión — el asistente nombró los campos, y solo tú llenas el secreto:
Claude CodeListo para conectar- TipoClave de API
- Tú ingresasla clave secreta
Dónde vive cada página de revisión
| Tu asistente propone… | Tú lo revisas en | Qué hace la página |
|---|---|---|
credentials.propose | /external/credentials/… | Llenas los campos privados, Conectar |
tools.propose | /external/tools/… | Revisas la herramienta, la pruebas, Crear |
db.propose | /external/databases/… | Editas columnas y vistas, Crear (multi-tabla) |
projects.propose | /external/memories/… | Revisas el proyecto y sus primeros hechos, Crear |
agents.propose | /external/agents/… | La vista real del constructor de agentes, Crear agente |
live_apps.stage | /external/live-app/… | La app funcionando, Guardar |
live_apps.theme | /external/live-app-theme/… | Eliges un look (eliges, no creas) |
automations.create | /external/automations/… | Revisas el borrador, lo pruebas y lo ejecutas |
| cualquier sesión | /external/session/… | Todo lo que pasó, sus archivos y configuraciones |
Las automatizaciones son la excepción a proponer y luego crear: automations.create escribe un
borrador inactivo de una vez, y la página /external/automations/… es donde lo revisas, lo
pruebas y lo ejecutas — encenderlo siempre es tu clic. Ver Automatizaciones y skills.
Las páginas de revisión viven dentro de Nirvai, no en un enlace público. Abrir una te pide iniciar sesión primero, y solo el dueño puede verla — un enlace de propuesta no se comparte.
Las acciones write — editar un registro, actualizar una observación — se aplican directo, sin
página de revisión. El paso de revisión protege crear cosas nuevas y todo lo que lleve un
secreto. Si quieres una configuración más estricta, crea un token sin write.
Cuando quieres un cambio
Las páginas de revisión no le mandan mensajes a tu asistente — no hay ningún canal desde Nirvai hacia tu chat. En vez de eso, la página te da un bloque para copiar y pegar; lo pegas de vuelta en tu asistente, que vuelve a redactar y a proponer. Ese bloque es la única vía de retorno, y por eso tu asistente debería esperar a que le digas que hiciste clic en vez de asumirlo.
Qué corre por su cuenta y qué apruebas tú
Dos cosas, de una en una: lo que tu asistente puede hacer en cuanto se lo pides, y lo que solo puede proponer para que tú lo termines. La línea se traza por función — casi toda lectura y los cambios del día a día corren por su cuenta; crear algo real, y todo lo que lleve un secreto, espera tu clic.
| Función | Corre por su cuenta | Necesita tu aprobación |
|---|---|---|
| Descubrimiento y sesiones | Listar y describir tus cosas, ejecutar acciones, leer el Feed de Actividad, mover archivos, bajar paquetes de habilidades. | Nada — solo leen o mueven cosas de sitio. |
| Proyectos | Recordar y guardar datos, actualizar notas, guardar archivos. | Crear un proyecto por una página de revisión es la opción por defecto, más suave. |
| Bases de datos | Leer registros; agregarlos y actualizarlos; crear tablas, espacios y vistas. | Una configuración de varias tablas pasa por una página de revisión. Borrar nunca es posible. |
| Conexiones (credenciales) | Solo mirar — listar e inspeccionar lo que ya conectaste. | Cada conexión nueva la apruebas tú. Los inicios de sesión de proveedores (Meta, LinkedIn, correo) solo puedes completarlos tú, en la propia página de Nirvai. |
| Herramientas | Ejecutar tus herramientas; construir una atada a una conexión que ya tienes. | Un kit propuesto se aprueba en una página de revisión; una herramienta que necesita un inicio de sesión de proveedor espera a que tú lo conectes. |
| Agentes | Leer, ejecutar, construir y editar agentes; adjuntar datos, conocimiento y habilidades. | También puedes aprobar un borrador de agente en una página de revisión. |
| Automatizaciones | Leer, construir y probar una automatización en borrador. | Solo tú activas una automatización — tu asistente nunca la activa. |
| Apps en vivo | Leer, construir, tematizar y probar un panel. | Tú haces clic en Guardar para publicarlo. |
Las bases de datos se pueden construir solas; las conexiones no. Tu asistente puede leer, agregar, actualizar e incluso crear bases de datos en cuanto se lo pides — la página de revisión es solo la vía extra para una configuración grande de varias tablas. Las conexiones son lo contrario: puede mirar las tuyas, pero cada una nueva la apruebas tú, y un inicio de sesión de proveedor (Meta, LinkedIn, correo) solo puedes completarlo tú.
Sesiones: un solo hilo de trabajo
Una sesión es un nombre que tu asistente elige para un trabajo — q3-report, por ejemplo. Todo
lo que ocurre bajo ese nombre se acumula en un mismo lugar: una ejecución en el Feed de Actividad,
una carpeta de archivos, un hilo que puedes retomar mañana.
Es más una carpeta de proyecto que un archivador: el trabajo relacionado se queda junto, y retomarlo es simplemente volver a nombrarlo.
Las sesiones son obligatorias para todo lo que produce o consume archivos — describir un elemento a fondo, descargar un paquete de referencia, ejecutar un script, ejecutar un agente, construir una live app. Las lecturas simples no necesitan una.
Qué vuelve
Toda acción devuelve el mismo sobre:
| Campo | Qué es |
|---|---|
result | Una vista previa acotada de lo que pasó |
reference_url | Un enlace directo a la cosa en Nirvai |
references | Enlaces relacionados (el registro, el agente, la app) |
session_url | La ejecución a la que perteneció |
Los resultados se previsualizan, nunca se guardan. El feed conserva lo que pediste y enlaza a lo que cambió — no los datos que volvieron. Cuando un resultado es genuinamente grande, tu asistente recibe un resumen más un identificador con el que puede pedir la versión completa, así una tabla de un millón de filas nunca tiene que viajar por un chat.
Si una conexión venció a mitad de la tarea, la acción devuelve un estado needs_auth con un enlace
para reconectar, en vez de fallar en silencio.
Descubrimiento, siempre
Dos reglas mantienen a tu asistente honesto con tus datos:
- Siempre por id, nunca por nombre. Dos tablas llamadas "Leads" son dos tablas distintas. Tu asistente resuelve primero cuál es la exacta.
- Pregunta, no asumas. La forma de tu base de datos — sus columnas, sus valores permitidos, a
quién se puede asignar — se consulta en vivo con
nirvai_describeantes de escribir nada. Tu asistente lee las reglas generales una vez; lee tus especificidades cada vez.
Tu asistente trabaja con referencias a tus cosas (este agente, esa tabla), nunca guardando tus datos. Cuando necesita el detalle, se lo pide a Nirvai en el momento. Así, ni siquiera una base de datos enorme tiene que pegarse en un chat.
Una columna que renombraste esta mañana ya está reflejada en lo que tu asistente ve esta tarde. No hay una copia en caché de tu esquema que pueda quedar desactualizada.