Referencia MCP

Revenue por el MCP

El espacio de verbos revenue.* para agentes externos — el paquete de skills de Revenue, el descubrimiento de verbos, las clases de verbo y roles mínimos, la aprobación del dueño en la app, el sobre de error y las preguntas de producto con docs.search.

Esta página es el contrato para un agente externo (Claude Code o cualquier cliente MCP) que maneja el espacio de Nirvai Revenue de un cliente. Cubre el espacio revenue.*, cómo descubrir y llamar sus verbos, qué llamadas necesitan a una persona y el sobre que devuelve cada verbo. Describe solo comportamiento observable. Para saber qué es Revenue, empieza en Primeros pasos con Nirvai Revenue.

---

Modelo de arquitectura

Un mismo registro de verbos atiende tres puertas: la app, el Asistente dentro de la app y este MCP. Cada verbo declara sus puertas, su clase, su rol mínimo y su control humano, así que un agente externo tiene exactamente las mismas reglas que el Asistente. No hay herramientas genéricas de crear/editar para Revenue: todo pasa por nirvai_execute con un alias revenue.*.

• El espacio existe solo dentro de un espacio de trabajo Revenue. Tu token debe pertenecer a uno; fuera de él, toda llamada revenue.* devuelve NOT_AVAILABLE.
• Aquí solo se pueden llamar los verbos cuyas puertas incluyen mcp. Los demás devuelven DOOR_NOT_ALLOWED.
• Una sesión por trabajo. Créala con nirvai_create_session y pásala en cada llamada, para que el dueño vea tu trabajo como un solo hilo en el feed de actividad.

Empieza: el paquete de skills

nirvai_download_skill_package(kind="revenue", session=…)
  → PACK.md        el índice: diez skills, cada una con su procedimiento, checklist y rechazos
  → workflow.md    cómo funciona esta puerta: sesiones, sobres, roles, el plan día a día
  → verbs_map.md   todos los verbos agrupados por tarea, con clase, rol mínimo, puertas, control y parámetros

El descubrimiento es en vivo: nirvai_describe(kind="revenue", ref="verbs") devuelve cada verbo con el esquema de sus parámetros. Lee revenue.workspace.get y revenue.checklist.get antes de cambiar nada, y trabaja en el primer ítem del checklist que no esté hecho.

Clases de verbo y roles

Los roles van seller < admin < owner < nirvai; cada verbo nombra el rol más bajo que puede llamarlo.

Clase	Qué hace una llamada	Control humano
read	Solo lee; segura en cualquier momento	ninguno
knob	Se aplica al tiro (horarios, pausas, destinatarios, etiquetas), queda registrada y se deshace con revenue.changes.undo	ninguno
structural	Va al único borrador abierto (embudos, etapas, Trabajos, entradas, Personas, funciones)	el Aprobar del dueño
mixed	Knob o structural según los argumentos	como arriba
lead_action	Actúa sobre un lead ahora (mover, nota, responder, programar)	ninguno
activation	Pone un Trabajo a trabajar con leads reales	el Activar del dueño o de un admin
team_admin	Miembros y sus accesos	ninguno
owner_only	Borrar o reiniciar un lead	lo hace el dueño en la app

Los pasos humanos vuelven como enlaces

En esta puerta no hay tarjetas de chat. Cada paso que solo una persona puede dar devuelve un open_url en el sobre: conectar WhatsApp o un calendario (revenue.connections.setup), aprobar el borrador (APPROVAL_REQUIRED) y activar un Trabajo (ACTIVATION_CLICK_REQUIRED). Entrega el enlace a la persona, espera y vuelve a revisar con el verbo de lectura (revenue.connections.check, revenue.templates.status, revenue.changes.diff, revenue.checklist.get).

Con un token de owner o admin construyes en un borrador (revenue.changes.open, luego los verbos structural, luego revenue.changes.diff); revenue.changes.publish sobre el borrador de un cliente devuelve APPROVAL_REQUIRED. Un token nirvai puede publicar sus propios borradores y activar Trabajos; ambas cosas quedan registradas con su nombre.

El sobre

{ "ok": true,  "data": { … }, "change_id": "…", "warnings": ["SMALL_SAMPLE"] }
{ "ok": false, "error": { "code": "NO_OPEN_CHANGE_SET",
                          "message_es": "…",
                          "hint": "Call revenue.changes.open first.",
                          "detail": { … } } }

hint dice qué hacer después y detail nombra el campo exacto. No repitas sin cambios una llamada que falló. warnings[] significa que la llamada funcionó pero algo merece una revisión.

Preguntas de producto

Para saber cómo funciona el producto, busca primero en la sección Revenue de esta documentación, lee el mejor resultado y cita su URL:

nirvai_execute(alias="docs.search", args={query: "aprobar activar", section: "revenue", lang: "es"})
nirvai_execute(alias="docs.read",   args={path: "/revenue/concepts"})

Si la sección no tiene resultados, docs.search busca en todo el sitio y marca la respuesta con section_fallback. El estado del espacio (qué existe, qué está activo) sale solo de los verbos, nunca de la documentación.

Límites y garantías

• Un agente externo nunca aprueba el borrador de un cliente ni activa su Trabajo con un token de owner: esos son clics en la app.
• Los leads de prueba nunca llegan a personas reales, así que prueba antes de pedir Aprobar.
• Los tokens de seller ven solo sus propios leads (NOT_YOUR_LEAD).
• Las lecturas de leads se paginan con cursor / next_cursor (revenue.leads.messages, revenue.leads.timeline).

Siguiente paso

• Referencia MCP — las herramientas maestras, las sesiones y las páginas de revisión.
• Web, medios y documentación — docs.search y docs.read en detalle.
• Las palabras de Revenue — qué es cada pieza de Revenue.