Tool Namespaces

nexus-mcp is one server, one connection, and one tools/list call. It does not split its tool families across separate servers or separate connections: a client that connects once and calls tools/list (or reads server/discover's capabilities in the current era) sees every namespace the running workspace can serve, together, in one response.

The families

Namespace	What it's for	Scope	Governed by
canvas_*	Reading and writing the shared, Excalidraw-compatible canvas	workspace	an explicit role grant on the target canvas
agent_*	Listing mesh peers, messaging them, and agent identity	workspace	the calling agent's mesh capability
window_*	Read-only window state and what is attached to a window	workspace	the calling agent's mesh capability
memory_*	The shared, durable knowledge memory	agent / workspace / global	visibility, plus the knowledge-runtime switch
provider_*	The AI provider registry and bridge runtime facts	app-wide	the calling agent's mesh capability
team_*	Team membership	app-wide	the calling agent's mesh capability
neural_*	Bounded traversal of the Neural Map	app-wide	the calling agent's mesh capability
browser_*	Observing and automating a NEXUS browser Window	per Window, within the workspace	mesh capability, plus a control lease and per-action approval
workspace_*	Read-only workspace identity and scope resolution	workspace	the calling agent's mesh capability
session_*	Terminal sessions: listing them, opening and closing one, arranging the panes, focusing one	workspace	autonomy mode, plus a per-agent creation limit on opening
insight_*	Read-only contribution, usage, and cost figures	agent / workspace	the calling agent's mesh capability
repo_* / worktree_*	Read-only repository and worktree layout, read from git's own bookkeeping files	workspace	the calling agent's mesh capability
room_*	Read-only presence, thought stream, zones, and mode for the local 2-D Room	workspace	the calling agent's mesh capability
settings_*	Durable app configuration, tiered — most fields are readable, few are writable, several are neither	app-wide	a closed allowlist, then autonomy mode
bit_*	Creating a Bit — a markdown note pane — with its text	workspace	autonomy mode, plus the creation limit
plan_*	Announcing a multi-step operation so you can watch, stop, and undo it	workspace	autonomy mode
tool_*	Read-only: this catalog, annotated with the caller's own live permissions	the calling agent	the calling agent's mesh capability

Every workspace-scoped family refuses a call that names or implies a different workspace. provider_*, team_*, neural_*, and settings_* are app-wide rather than workspace-scoped: provider and app configuration are NEXUS-wide settings, teams are not partitioned by workspace today, and the Neural Map is one shared graph.

A few tool names sit under a prefix that belongs to another family — agent_launch, session_arrange, session_focus, browser_focus, browser_open_window, browser_close_window, canvas_create, canvas_delete, session_create, session_close. They are routed by exact name rather than by prefix, so the family a tool's prefix suggests is not always the code that answers it. This matters only if you are filtering tools by prefix on the client side: filter by name.

See MCP Tools for the full per-tool table, and Canvas: Roles & Permissions and Agent Mesh: Capabilities & Limits for what the two oldest families' gating means in practice.

Every description declares its plane

Every tool description this server serves opens with the same marker:

[Local NEXUS app] List the canvases the calling agent may read in its workspace.

That prefix is not decoration. If you also have the Chainabit cloud MCP server connected, you have two agent_create tools, two memory systems, two agent rosters, and two things called a "workspace" — none of which are related. A tool's description is the signal a model reads most reliably when choosing between them, so this server states its plane in every one, first.

If a tool description you receive does not carry that marker, it did not come from this server. See NEXUS local MCP vs Chainabit cloud MCP for the full boundary, including which similarly-named tools belong to which plane.

Discovering what's actually there

tools/list is served live by the running workspace, never from a cached or stale catalog — which also means it fails closed with no workspace running rather than returning an empty list or a remembered one. Call it (or read server/discover's capabilities in the 2026-07-28 era) after connecting, rather than hardcoding tool names from documentation: exact input schemas belong to tools/list's live response, and this page and the tools reference describe purpose and outcome contracts that stay stable across releases even as individual argument shapes are refined.

tools/list also narrows to what a given connection can actually serve. A namespace whose underlying surface is unavailable is not advertised at all, rather than advertised and then answered with an error.

Two resources are worth reading before you call anything unfamiliar:

• nexus://capabilities — every tool's required capability, approval level, side effects, and reversibility where annotated.
• nexus://planes — what this server is and what it is not.

Both are covered in MCP Protocol § resources/list and resources/read.

Those two describe the shape of the bridge and read identically for every caller. When you need to know what you may do — which tools your capability set and your autonomy mode would actually let through right now — call tool_list instead. See MCP Tools § Tool introspection.

Read vs. write, across every family

Reads and writes behave differently enough to design around, and the difference is consistent across the whole surface:

• A read (canvas_list, agent_list_peers, window_read, memory_query, provider_list, team_list, neural_neighbors, browser_read_page, workspace_current, tool_list) returns current state and nothing more. Reads are never gated by the agent's autonomy mode.
• A write on the canvas never returns a bare success/failure — it returns one of four outcomes, detailed in Canvas: Revisions & Conflicts.
• A write on the mesh (agent_trigger, agent_invite_to_channel, agent_create) returns once the action is queued or requested, not once anything downstream has happened — detailed in Agent Mesh: Delivery Semantics.
• A write on shared memory is synchronous: the entry is visible to the next memory_query or memory_list immediately.
• A write in the browser is additionally subject to a control lease and, for sensitive actions, to a human's approval.
• A write that creates a surface (session_create, agent_launch, browser_open_window, canvas_create, bit_create) is synchronous and charged against the calling agent's creation budget at admission — including when it then fails, so a retry loop is not free.

No family's write behaves like a synchronous remote procedure call in the sense of "returns when the effect is fully settled everywhere."

Autonomy applies to every namespace

A write is not dispatched until the calling agent's autonomy mode allows it. That enforcement is uniform across the whole tool surface, decided above the per-namespace routing, so a newly added namespace cannot introduce an ungoverned write surface. Reads always pass; irreversible actions always reach a human, in every mode. The four modes and what each one returns are documented in MCP Tools § Autonomy.

One family can't stand in for another

Nothing in agent_* reads or writes the canvas, and nothing in canvas_* addresses another agent. window_* never mutates a window; workspace_* never changes one. If you're building a workflow that draws on the canvas and hands off to another agent, that's two calls from two namespaces, not one combined call — see Canvas: Driving the Canvas from an Agent and Agent Mesh: Sending Messages for each half.

Furnishing a workspace, and the one thing that is never creatable

An agent may furnish a workspace you have already opened: it can open a terminal (session_create), start an agent working in one (agent_launch), open a browser window and start its engine (browser_open_window), create a canvas (canvas_create), and add a Bit (bit_create). Each ships with its inverse, and each is charged against a per-agent rate limit and lifetime cap — a refusal names the limit and when it resets.

It cannot create a workspace. There is no workspace_create, on this server or anywhere, by design: an agent may occupy a scope it was placed in, never manufacture one for itself.

Everything an agent creates is attributed to it in the NEXUS UI — a badge on the pane, the sidebar row, and the canvas row — and survives a relaunch, so a surface you did not open yourself always says who did.

Arranging, focusing, and the window a headless call may touch

session_arrange acts on the workspace's own pane layout, so it is unambiguous however many windows you have open, and every window showing that workspace reflects the change.

session_focus and browser_focus are different: selection belongs to a window, so these act on the window you are currently looking at, and only while that window is showing the calling agent's workspace. If you have switched to another workspace, the call is refused with a message saying what you are looking at instead. An agent cannot reach into a background window — moving something you cannot see is worse than moving something you can.

Watching, stopping, and undoing a multi-step operation

Before making several changes that only make sense together, an agent can call plan_begin to announce them. The plan appears in NEXUS while it runs, showing what was announced next to what has actually happened.

A plan grants the agent nothing. It cannot execute anything — there is no plan_execute, and the steps are the agent's ordinary tool calls, each gated exactly as it would be otherwise. The record is written by the server as it dispatches, not by the agent describing itself, so an agent cannot omit a step from its own plan.

You can stop a running plan. Its remaining writes are then refused; its reads keep working, so the agent can still find out what did and did not happen and tell you, rather than guessing. You can then undo it, which closes the surfaces it created, newest first. Undo is honest about its limits: it reports what it cannot restore — a pane arrangement has no recorded prior geometry — before you commit to it.

What isn't exposed

There's no tool that grants or changes a canvas role, no tool that opens or closes a NEXUS application window (browser windows inside one are a different thing, and are creatable), and no tool that creates, switches, or deletes a workspace. See MCP Tools's "What isn't here" section for the complete list of gaps and the reasoning behind each, rather than assuming a tool exists because the capability it would control does.

Where to go next

• MCP Tools — the exhaustive per-tool table.
• NEXUS local MCP vs Chainabit cloud MCP — telling the two servers apart.
• Connect a Client — getting to the point where tools/list returns something at all.
• Troubleshooting — what it looks like when discovery itself fails.