MCP reference
Web, media & docs
The `web`, `media` and `docs` action surfaces — search and read the open web, generate and edit images, and answer from Nirvai's own official documentation.
Every other area of the connection reaches into your account — your records, your agents, your
projects. These three reach outward instead. They are the assistant's own toolbox: bolted to the
workbench, identical for everyone, owned by nobody. A tape measure doesn't belong to the house you
are measuring, and web.search doesn't belong to your data.
Everything here runs through nirvai_execute under the web, media and docs areas. Read
the MCP reference first if the alias grammar is new to you.
The verbs
| Verb | Scope | What it does |
|---|---|---|
web.search | run | Search the open web and get back ranked results. |
web.fetch | run | Read one page end to end, as text. |
media.image | run | Generate an image from a written prompt. |
media.image_edit | run | Edit or combine images that already exist. |
docs.search | read | Find the right page in Nirvai's official documentation. |
docs.read | read | Load one documentation page in full, with its public link. |
docs.index | read | Get a map of the whole documentation site. |
These are fixed verbs, not things you own. They never show up in nirvai_list_resources —
there is nothing to discover, because every account gets exactly these seven.
Posting to Meta, opening a GitHub issue, sending on a channel — those are your saved tools, under
Tools & connections. web and media are only the four built-ins above.
Web: search, then read
web.search takes a query and returns ranked results — title, link and snippet each. search_type
chooses the kind of search (search, news, images, shopping, places, maps, scholar),
num how many results, date_filter how recent (all, or a window like qdr:w for the past week),
and location which country or city to search from.
web.fetch takes a single url and returns that page's readable text. A YouTube link returns the
transcript rather than the page furniture.
The pairing is the point: search says which page is worth reading, fetch is what actually reads it. An answer assembled from snippets alone is an answer assembled from headlines.
Media: generate and edit
media.image needs a prompt, and accepts aspect_ratio (1:1 unless you say otherwise) and
output_format (png, jpeg, webp). media.image_edit needs a prompt plus image_urls — up to
four images to edit or combine, given either as public links or as handles from
nirvai_transfer_file.
You never pass a model. The right one is chosen for you, and it improves without you changing anything.
Every generation is a real run. A good assistant produces two or three and picks one, rather than grinding out twenty variations on the way to a header image.
Docs: the product's own manual
docs.* queries this documentation site — the pages you are reading right now. It is the one
area that touches nothing of yours: public product documentation, read-only, and no session
required.
It exists so your assistant answers from what Nirvai does today rather than from what it half
remembers. The /nirvai:help command is exactly this, wrapped up: search, read, answer, cite the
page.
Search with short keywords, not a sentence — ranking is keyword-based, so whatsapp channel
finds the page while "how do I connect WhatsApp to an agent" drifts. docs.read then takes a
path from those results and returns the full page plus the public url to cite. docs.index
returns the site map when your assistant would rather scan than search.
Worked examples
Research a company, then write it down. Search for candidates, read the one that matters, and only then touch your database:
nirvai_execute(
alias = "web.search",
args = { query: "Acme Corp funding round", search_type: "news", date_filter: "qdr:y" },
description = "Find recent news about Acme's funding"
)
nirvai_execute(
alias = "web.fetch",
args = { url: "https://example.com/acme-series-b" },
description = "Read the Series B announcement in full"
)
Make a header image for a newsletter issue:
nirvai_execute(
alias = "media.image",
args = { prompt: "A quiet desk at sunrise, warm light, editorial photography",
aspect_ratio: "16:9", output_format: "png" },
description = "Generate the header image for issue #1"
)
Check the product before promising it. When your assistant is unsure whether Nirvai supports something, it looks it up instead of guessing:
nirvai_execute(alias = "docs.search", args = { query: "kanban view" },
description = "Find the docs page on board views")
nirvai_execute(alias = "docs.read", args = { path: "/databases/views" },
description = "Read the views page before answering")
Limits & guarantees
- Results are bounded. A generated image comes back as a link you can open and a fetched page as bounded text — never raw bytes pasted into your chat. Large results return a summary plus a handle your assistant can use to pull the whole thing.
docs.*needs no session and no data access. It is public documentation,readscope only, and it works before you have created anything in Nirvai at all.web.*andmedia.*needrun. They execute something, so aread-only token is refused — cleanly, with the reason.- Nothing here writes to your account. Searching, fetching and generating produce results; they do not create records, tools or files in Nirvai unless a separate action does that next.
- No model names, ever. Image generation and search are chosen and tuned on Nirvai's side; there is no model argument to get wrong, and no version for your assistant to pin.
- Everything still lands in the feed. Each call carries its
description, so "Read the Series B announcement in full" is what you see in the Activity Feed — not a bare URL.