MCP reference

Revenue over the MCP

The revenue.* verb namespace for external agents — the Revenue skill package, verb discovery, verb classes and minimum roles, owner approval in the app, the error envelope and product questions through docs.search.

This page is the contract for an external agent (Claude Code or any MCP client) that drives a client's Nirvai Revenue workspace. It covers the revenue.* namespace, how to discover and call its verbs, which calls need a human, and the envelope every verb returns. It describes observable behavior only. For what Revenue is, start at Quick start with Nirvai Revenue.

---

Architecture model

One verb registry serves three doors: the app, the in-app Assistant and this MCP. Each verb declares its doors, its class, its minimum role and its human gate, so an external agent has exactly the same rules as the Assistant. There are no generic create/update tools for Revenue: everything goes through nirvai_execute with a revenue.* alias.

• The namespace exists only inside a Revenue workspace. Your token must belong to one; outside it, every revenue.* call returns NOT_AVAILABLE.
• Only verbs whose doors include mcp are callable here. The others return DOOR_NOT_ALLOWED.
• One session per job. Create it with nirvai_create_session and pass it on every call, so the owner sees your work as one thread in the activity feed.

Start: the skill package

nirvai_download_skill_package(kind="revenue", session=…)
  → PACK.md        the index: ten skills, each with its procedure, checklist and refusals
  → workflow.md    how this door works: sessions, envelopes, roles, the day-by-day plan
  → verbs_map.md   every verb grouped by task, with class, min role, doors, gate and params

Discovery is live: nirvai_describe(kind="revenue", ref="verbs") returns every verb with its params schema. Read revenue.workspace.get and revenue.checklist.get before changing anything, and work on the first checklist item that is not done.

Verb classes and roles

Roles rank seller < admin < owner < nirvai; each verb names the lowest role that may call it.

Class	What a call does	Human gate
read	Reads only; safe any time	none
knob	Applies at once (hours, pauses, recipients, labels), logged and undoable with revenue.changes.undo	none
structural	Lands in the single open draft (funnels, stages, Jobs, entries, personas, functions)	the owner's Aprobar
mixed	Knob or structural depending on the args	as above
lead_action	Acts on one lead now (move, note, reply, schedule)	none
activation	Turns a Job on for real leads	the owner's or an admin's Activar
team_admin	Members and their access	none
owner_only	Erase or restart a lead	done by the owner in the app

Human steps come back as links

There are no chat cards on this door. Every step only a human can take returns an open_url on the envelope: connecting WhatsApp or a calendar (revenue.connections.setup), approving the draft (APPROVAL_REQUIRED) and activating a Job (ACTIVATION_CLICK_REQUIRED). Hand the link to the human, wait, then re-check with the read verb (revenue.connections.check, revenue.templates.status, revenue.changes.diff, revenue.checklist.get).

With an owner or admin token you build in a draft (revenue.changes.open, then structural verbs, then revenue.changes.diff); revenue.changes.publish on a client's draft returns APPROVAL_REQUIRED. A nirvai token may publish its own drafts and activate Jobs; both are logged with its name.

The envelope

{ "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 says what to do next and detail names the exact field. Do not retry a failed call unchanged. warnings[] mean the call worked but something needs a look.

Product questions

For how the product works, search this documentation's Revenue section first, then read the best hit and cite its URL:

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

With no match in the section, docs.search falls back to the whole site and marks the reply with section_fallback. Workspace state (what exists, what is live) comes only from verbs, never from the docs.

Limits & guarantees

• An external agent never approves a client's draft or activates a client's Job with an owner token: those are clicks in the app.
• Test leads never reach real people, so test before asking for Aprobar.
• Seller tokens see only their own leads (NOT_YOUR_LEAD).
• Lead reads page with cursor / next_cursor (revenue.leads.messages, revenue.leads.timeline).

What's next

• MCP reference — the master tools, sessions and review pages.
• Web, media & docs — docs.search and docs.read in full.
• The words of Revenue — what each Revenue entity is.