MCP reference
This is the technical companion to the MCP documentation. It describes the observable contract: the tools your assistant sees, the actions it can name, what each one returns, and the rules the connection enforces before anything runs.
You do not need to memorise any of this — your assistant downloads the same reference on demand. Read it when you want to know exactly what your assistant is able to do, or why it did something.
The seven master tools
Your assistant never sees hundreds of separate tools. It sees seven, and everything else is an argument to one of them.
Think of a library. You don't get one door per book — you get a catalogue (find something), a call number (name the exact copy), a reading desk (use it), a loan record (what you took out today), and a photocopier (get pages in and out). Seven doors, an entire library behind them.
| Tool | What it does |
|---|---|
nirvai_execute | The one action verb. Every capability runs through it: nirvai_execute(alias, args, description). |
nirvai_list_resources | "What do I have?" — lists your things of a given kind, each with a stable id. |
nirvai_describe | "What exactly is this one?" — the live contract for a single item. |
nirvai_get_session | Reads back a run: what happened, and the files it produced. |
nirvai_transfer_file | Moves files between your assistant's machine and Nirvai. |
nirvai_download_skill_package | Pulls the instructions for one area (databases, agents, …) on demand. |
nirvai_sync_session | Keeps a working folder in step — list, pull, push. |
Assistants get worse as their tool list grows — the choice gets noisy. One verb with a named action keeps the menu short and the reasoning sharp, and it means a new Nirvai capability works in your assistant immediately, with no update on your side.
The alias grammar
Every action is a two-part name: area.action.
nirvai_execute(
alias = "db.select",
args = { table_session: "…", condition: "WHERE status = 'Open' LIMIT 50" },
description = "Check which deals are still open"
)
The area decides which part of Nirvai answers, how the result is deep-linked, and which permission is required. These are the areas:
| Area | What lives there | Reference |
|---|---|---|
memory | Long-term facts, people, decisions | Memories |
db | Your records, tables and spaces | Databases |
tools · credentials | Your saved tools and connections | Tools & connections |
agents | Building and running your agents | Agents |
live_apps | Interactive dashboards on your data | Live apps |
automations · workflows · skills | Scheduled and reusable work | Automations & skills |
web · media · docs | Search, images, official documentation | Web, media & docs |
description is never optional
Every action carries a short, human "why". It is what turns the Activity Feed into something you can actually read — "Check which deals are still open" rather than "db.select". If your assistant ever seems to be acting opaquely, the feed is where you look.
Permissions: four tiers
The token you mint carries scopes, and the connection checks them before it decides what the action even means. It's the difference between a library card that lets you read and one that lets you re-shelve.
| Scope | Allows | Needs your approval? |
|---|---|---|
read | Look at anything — list, describe, recall, select | No |
run | Use something that already exists — run a tool, run an agent, test a script | No |
write | Change something that exists | Changes land directly |
create | Make something new | Creating goes through a review page |
| destructive | Delete | Cannot be granted. Refused for every token. |
Deleting is deliberately impossible over the connection. If an assistant tells you it deleted something in Nirvai, it did not.
Nothing is created behind your back — the review page
For anything that creates a real thing — a connection, a tool, a database, an agent, a live app — your assistant does not build it. It proposes it, and hands you a link to a review page inside Nirvai with a single Create/Connect button. You see exactly what will be made, you can change it, and nothing exists until you click.
This is the single most important thing to understand about the connection, so here it is end to end:
Three things follow from that shape:
- The assistant never learns your secret. It proposes "an API key goes here"; you type the key on Nirvai's own page. The value never touches the assistant, the result, or the feed.
- You can edit before you commit. The page is a real form, not a receipt — change a column type, rename a table, drop a tool you don't want, then click.
- It cannot be clicked twice. Once created, re-opening shows Created ✓ and refuses to make a second copy. Your assistant learns the new id from the feed, not by proposing again.
Where each review page lives
| Your assistant proposes… | You review at | What the page does |
|---|---|---|
credentials.propose | /external/credentials/… | Fill the private fields, Connect |
tools.propose | /external/tools/… | Check the tool, test it, Create |
db.propose | /external/databases/… | Edit columns and views, Create (multi-table) |
memory.propose | /external/memories/… | Review the store and its first facts, Create |
agents.propose | /external/agents/… | The real agent builder view, Create agent |
live_apps.stage | /external/live-app/… | The working app, Save |
live_apps.theme_propose | /external/live-app-theme/… | Pick a look (choose, don't create) |
automations.propose | /external/automations/… | Read-only preview; you finish in Nirvai |
| any session | /external/session/… | Everything that happened, its files and setups |
Review pages live inside Nirvai, not on a public link. Opening one signs you in first, and only the owner can see it — a proposal link is not shareable.
write actions — editing a record, updating an observation — land directly, with no review page.
The review step guards creating new things and anything holding a secret. If you want a stricter
setup, mint a token without write.
When you want a change
Review pages don't send messages back to your assistant — there is no channel from Nirvai into your chat. Instead the page gives you a copy-paste block; you paste it back into your assistant, which re-authors and re-proposes. That block is the only feedback path, which is why your assistant should wait for you to say you clicked rather than assuming.
Sessions: one thread of work
A session is a name your assistant picks for a piece of work — q3-report, say. Everything under
that name accumulates in one place: one run in the Activity Feed, one folder of files, one thread to
resume tomorrow.
It's a project folder rather than a filing cabinet: related work stays together, and picking it up again means naming it again.
Sessions are required for anything that produces or consumes files — describing an item in depth, downloading a reference pack, running a script, running an agent, building a live app. Plain reads don't need one.
What comes back
Every action returns the same envelope:
| Field | What it is |
|---|---|
result | A bounded preview of what happened |
reference_url | A link straight to the thing in Nirvai |
references | Related links (the record, the agent, the app) |
session_url | The run this belonged to |
Results are previewed, never stored. The feed keeps what you asked for and links to what changed — not the data that came back. When a result is genuinely large, your assistant gets a summary plus a handle it can use to fetch the full thing, so a million-row table never has to travel through a chat.
If a connection has expired mid-task, the action returns a needs_auth status with a link to
reconnect, rather than failing silently.
Discovery, every time
Two rules keep your assistant honest about your data:
- Always by id, never by name. Two tables called "Leads" are two different tables. Your assistant resolves the exact one first.
- Ask, don't assume. The shape of your database — its columns, its allowed values, who can be
assigned — is fetched live with
nirvai_describebefore anything is written. Your assistant reads the general rules once; it reads your specifics every time.
A column you renamed this morning is already reflected in what your assistant sees this afternoon. There is no cached copy of your schema to go stale.