Referencia MCP
Este es el complemento técnico de la documentación MCP. 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. Léela cuando quieras saber exactamente qué es capaz de hacer tu asistente, o por qué hizo algo.
Las siete herramientas maestras
Tu asistente nunca ve cientos de herramientas separadas. Ve siete, 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). Siete 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_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 |
|---|---|---|
memory | Hechos, personas y decisiones a largo plazo | Memorias |
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 · workflows · skills | Trabajo programado y reutilizable | Automatizaciones y skills |
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.
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) |
memory.propose | /external/memories/… | Revisas la memoria 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_propose | /external/live-app-theme/… | Eliges un look (eliges, no creas) |
automations.propose | /external/automations/… | Vista previa de solo lectura; terminas en Nirvai |
| cualquier sesión | /external/session/… | Todo lo que pasó, sus archivos y configuraciones |
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.
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.
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.