Skip to content

Explanation

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 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 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.
  • 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).