Plugins and connectors¶

Nawa's own tools are fixed, reviewed and classified in advance. Everything else it can reach — a service's API, a program on the machine, a browser it does not own — arrives as an MCP server: tools discovered at run time from software Nawa did not write. This page explains how those tools are admitted, classified, offered to the model, and run, and why the design keeps them at arm's length.

Two doors, one registry¶

A connector is an MCP server added on the Connectors tab: a remote endpoint with OAuth sign-in, or a local command. A plugin is a package — plugin.json, an optional mcp.json, skills, an optional view — installed from the catalogue or a folder, which registers its own MCP server. Both land in the same registry with the same permissions per tool; the catalogue plugin only adds a versioned snapshot, a verified download for any native runtime, and a page of its own.

The catalogue ships with Nawa and names reviewed package sources with SHA-256 hashes for any platform runtime; a third-party manifest cannot nominate a runtime download. Add from folder copies a snapshot, so editing the folder afterwards changes nothing until it is installed again.

Discovery per turn, tools on demand¶

At the start of a turn, and of each coder session of a background build, the engine lists the tools of every enabled, connected server and classifies each from what you granted it — always allow, ask first, blocked, or automatic for a plugin. A tool's fingerprint travels with the turn: if a server changes a tool's schema mid-turn, the call is refused rather than run against a contract the model did not see.

The model does not receive every plugin tool up front. It receives a catalogue — each plugin with its name, description and tool count — and a load_plugin_tools tool to list a plugin's tools and load the ones it needs into this turn's tool list. A loaded tool's schema is the server's own, verbatim. Loading is deliberate and bounded; it keeps ordinary turns light and keeps a plugin from expanding the prompt of every chat.

Running a tool¶

A call goes through the same permission gate as a native tool, with a card that names the plugin and the tool; "Always allow" on a card sets the same thing for the rest of the chat. The engine owns the MCP session: for a local server it starts the process with Nawa's bundled Node, npx, Git and ripgrep on its path, reuses it between calls, and closes it when the plugin is disabled, removed, or Nawa exits. For a remote server it renews credentials before each call rather than trusting the token captured at sign-in, and the result carries what credential was presented, so a refusal is distinguishable from never having signed in.

A local server is told the folder it may work in as its MCP root: the workspace of the chat that calls it, which is the chat's project folder or, outside a project, the chat's own folder. A background build's calls give the build's own folder instead, where its coder works until the build delivers its verified result to the chat. Plan mode stops a call before it reaches a server, and a folder outside the workspace is approved one action at a time, which an MCP call cannot carry, so it is never a root. A server works for one folder at a time: a call for another chat's folder or a build's waits for the running calls to finish, and a server that has read its roots restarts with the new folder, since it may apply a changed list only after its next call. What a local server writes there during a reply is part of that reply's checkpoint, as the assistant's own changes are; in a build it is part of what the build delivers. A remote server is told no folders of this computer.

A local server does not start in the workspace. It runs in the working folder its connection names, its package folder for a plugin, or Nawa's own folder. A launcher such as npx chooses the code it runs from the folder it starts in, and sandboxed commands can write the workspace without asking, so starting there would let them choose what runs with your account's full access. A relative path therefore resolves outside the server's roots, and a server that keeps to its roots refuses it.

A result is delivered as the server returned it. Binary content is moved into the immutable evidence store and referenced; text stays as text. A server that lists its tools to anyone but refuses to run them is shown as Needs authentication the first time it refuses, instead of staying "Connected" while every call fails.

Browser plugins use their native tools¶

Browser plugins follow the same discovery, authorization, execution and observation path as other plugins. The main model loads their native tools and chooses actions directly. Nawa does not decorate browser schemas with decision-model fields or run a separate browser agent loop. Permission checks and external-content screening still apply.

Why¶

Run-time discovery, per-turn classification and fingerprints, because a tool Nawa did not write cannot be in the static security manifest, and the model must never call a contract it did not see.
A catalogue plus explicit loading, because thirty plugin tools in every prompt would cost every chat for the sake of the one that needs them.
Sessions owned by the engine, because a plugin process that outlives its owner is the same defect as a command that outlives its turn.
Roots from the calling chat or build, one folder at a time, because a server that keeps to its roots should reach the folder that work may use and never another's. A build's folder is its own because the build delivers its result only once verified, and a server writing into the chat's folder would bypass that.
Facts about credentials in every result, because "unauthorised" and "never signed in" call for different actions and looked identical once.

Evidence: PLUGINS.md (the package format and the first catalogue plugin), docs/connector-directory-and-chrome-control-2026-09-18.md (the directory, sign-in without a client of your own, the permissions list), docs/browser-direct-removal-2026-09-24.md (the direct browser boundary).