MCP reference
Automations & skills over MCP
How your assistant drafts an automation, tests and runs it, turns it on (only when it's ready), and runs a single saved skill in Nirvai's cloud.
Two neighbouring areas of the connection. automations covers work that repeats on its own — draft
it, test it, run it, turn it on. skills covers one saved piece of work, run once, on demand.
Draft, test, run — and turn on only when it's ready
Your assistant can wire in a timer switch — choose the hour, run the cable, mount the plate, and even test that the wiring works. It can flip the breaker too, but only on a switch that is actually finished: the connection refuses to activate a half-wired automation (a trigger still missing its connection, a step that doesn't resolve) and tells you exactly what's missing. Creating one never turns it on by itself — that stays a deliberate act.
| Action | Scope | What it does |
|---|---|---|
automations.describe_schema | read | The shape a valid automation has — kinds of trigger, how steps chain, the two run modes. |
automations.templates | read | The catalogue of real triggers (a new deal, a form response, …) and their sample payloads. |
automations.validate | read | Check a design is sound before creating it. |
automations.create | create | Authors the automation straight into your account as an inactive draft. |
automations.update | write | Edit an automation you already have. |
automations.test | run | Run it once in place and hand back per-step results and a link to that run. |
automations.execute | run | Run it for real with an input payload of your assistant's choosing. |
automations.activate · automations.deactivate | write | Turn it on or off. Activation is refused until the automation can actually fire. |
automations.runs | read | The run history, or one run's per-step detail, to see what happened or why it failed. |
skills.run | run | Runs one saved skill in Nirvai's cloud, addressed by its slug. |
Automations are the one area that skips propose-then-create: automations.create writes the real
(inactive) draft in one step. The old automations.propose and workflows.trigger names are gone —
calling them returns a note pointing you at automations.create / automations.execute.
What your assistant actually authors
An automation is a small, explicit design: a name, a trigger (manual, cron with a schedule and
time zone, or an app event from the template catalogue), the agents it may use — existing agents of
yours, named by their own ids — and the steps, each saying which agent runs, what it's asked to do,
and where the flow goes next on success or failure. An optional execution_mode picks between the
quick default and the mode meant for long or heavy jobs.
nirvai_execute(
alias = "automations.create",
args = { name: "Monday pipeline digest",
trigger: { type: "cron", cron: "0 9 * * 1", timezone: "America/Santiago" },
agents: ["sales-analyst"],
steps: [{ node_idx: 1, from_idx: 0, type: "agent", name: "Summarise",
agent: "sales-analyst",
input_prompt: "Summarise last week's closed and stalled deals." }] },
description = "Draft a Monday morning pipeline digest"
)
Files and demo data
Your assistant knows how automations move files for free — attaching a database file to an email, saving it into a project, posting a project image — and it always fills in the automation's demo data when it creates one. To find a project file, it lists your projects with nirvai_list_resources(kind="projects") — each marked with whether you own it, since only projects you own can receive files — and then the files inside with projects.list_files.
Where you review and run it
automations.create hands you a link to /external/automations/…. Unlike the other review pages this
one is live: you see the canvas, run it with an input, watch the recent runs, and — once it's
ready — switch it on. Every test and execute also returns a run link so you can open that exact
run and read its per-step output.
- Turning it on is gated, not blocked. With a
write-scoped token your assistant can activate a ready automation; a not-yet-ready one is refused with the exact blocker (often a connection the trigger still needs). It never activates silently on create. - If a trigger needs a login, your assistant proposes the connection through the credential verbs and hands you the secure page — the secret is still typed by you. See Tools & connections.
skills.runinvolves no review page; it runs a skill you already have and returns the result.
Skills: one saved procedure, run in the cloud
A skill is a piece of real code your agents already have available. skills.run runs exactly one
of them — named by its slug, never by display name — on Nirvai's side, with a genuine working folder
underneath it. Files it produces sync back into your session, so your assistant can pick them up in
the next step.
nirvai_execute(
alias = "skills.run",
args = { skill: "bulk-enrich", module: "main", entry: "run",
args: { table_session: "8e0438a3-…" },
tool_ids: [1697], session: "q3-cleanup" },
description = "Enrich this quarter's new accounts with company size"
)
It's the opposite end of the spectrum from a live-app data script, and the contrast is deliberate:
| Live-app data script | skills.run | |
|---|---|---|
| Imports, files, network | None — pure data in, pure data out | A full environment, with a working folder |
| Can change your records | Never | Yes, if the tools it's given allow it |
| What runs | Code written for that app, checked line by line | A known, saved skill, fetched by slug |
| Session | Required | Required — it's what the working folder belongs to |
A live-app script is deliberately caged because it's newly written code. A skill isn't caged in the
same way because it isn't new — it's the same procedure your agents already run, and there is no way
to hand skills.run free-form code instead.
Limits & guarantees
- Create makes a draft. A new automation is inactive;
automations.activateis a separate act, and it's refused until the automation can actually fire. - Existing agents only. Steps reference agents you already own; an unknown one is refused before anything is written.
- Calling create twice makes two. Automation creation isn't idempotent — a repeat call is a second
automation, not an update; use
automations.updateto change one. - Runs on Nirvai, and it's logged.
test/executerun on Nirvai's side, consume credits whoever drafted them, and every run is addressable by a link in the Activity Feed. - Known skills only.
skills.runtakes a slug, a module and an entry point — not a body of code, and only reaches the tools and tables named on the call. - Bounded results. Output comes back as a capped preview plus a downloadable handle. Long runs return as still-running rather than silently hanging.
- Different keys. Drafting needs
create; editing, turning on/off needwrite; testing, running and skills needrun. See scopes.