MCP reference
MCP reference
The complete action surface your assistant can call over MCP — the seven master tools, the alias grammar, scopes, sessions, and how results come back.
Once connected, your assistant gets something like a universal remote for Nirvai — a small, consistent set of buttons that reach every part of your account: projects, databases, tools and connections, agents, live apps, automations, and web search. This page 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, and the slash commands kick off the right steps for you. Read it when you want to know exactly what your assistant is able to do, or why it did something.
The master tools
Your assistant never sees hundreds of separate tools. It sees a short, fixed set, 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). A handful of 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_create_session | Opens a named run up front, so later actions can address it by id. |
nirvai_list_sessions | Lists your recent runs, so your assistant can pick one back up. |
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 |
|---|---|---|
projects | Long-term facts, people, decisions | Projects |
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 · skills | Scheduled and reusable work | Automations & skills |
web · media · docs | Search, images, official documentation | Web, media & docs |
Two areas were renamed: memory → projects, and workflows → automations. The old names are
deprecated — calling one returns an error that points to the new name and asks your assistant to
re-download that area's skill package.
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.
Here is what a proposed connection looks like when you open its review page — the assistant named the fields, and only you fill in the secret:
Claude CodeReady to connect- TypeAPI key
- You enterthe secret key
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) |
projects.propose | /external/memories/… | Review the project 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 | /external/live-app-theme/… | Pick a look (choose, don't create) |
automations.create | /external/automations/… | Review the draft, test it and run it |
| any session | /external/session/… | Everything that happened, its files and setups |
Automations are the one exception to propose-then-create: automations.create writes an inactive
draft straight away, and the /external/automations/… page is where you review, test and run it —
turning it on is always your click. See Automations & skills.
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.
What runs on its own vs. what you approve
Two areas, one at a time: what your assistant can do the moment you ask, and what it can only propose for you to finish. The line is drawn per feature — most reading and everyday changes run on their own; creating a real thing, and anything holding a secret, waits for your click.
| Feature | Runs on its own | Needs your approval |
|---|---|---|
| Discovery & sessions | List and describe your things, run actions, read the Activity Feed, move files, pull skill packs. | Nothing — these only ever read or move things around. |
| Projects | Recall and save facts, update notes, store files. | Creating a project through a review page is the gentler default. |
| Databases | Read records; add and update them; create tables, spaces and views. | A whole multi-table setup goes through a review page. Deleting is never possible. |
| Connections (credentials) | Only look — list and inspect what you've already connected. | Every new connection is yours to approve. Provider logins (Meta, LinkedIn, email) can only ever be completed by you, on Nirvai's own page. |
| Tools | Run your tools; build one that's bound to a connection you already have. | A proposed toolkit is approved on a review page; a tool that needs a provider login waits until you connect it. |
| Agents | Read, run, build and edit agents; attach data, knowledge and skills. | You can also approve an agent draft on a review page. |
| Automations | Read, build and test a draft automation. | Only you turn an automation on — your assistant never activates one. |
| Live apps | Read, build, theme and test a dashboard. | You click Save to publish it. |
Databases can be built on their own; connections cannot. Your assistant can read, add, update and even create databases the moment you ask — the review page is only the extra path for a big multi-table setup. Connections are the opposite: it can look at yours, but every new one is yours to approve, and a provider login (Meta, LinkedIn, email) can only ever be completed by you.
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.
Your assistant works with references to your things (this agent, that table), never by holding your data. When it needs the detail, it asks Nirvai for it just-in-time. So even a huge database never has to be pasted into a chat.
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.