Connect a Client

This page is about the moment a CLI coding agent starts speaking to NEXUS as an MCP client — calling canvas_* and agent_* tools rather than just running shell commands in a terminal pane. It applies the same way whether that CLI is one NEXUS launched for you in its own pane, or a CLI process running entirely outside NEXUS. In both cases the CLI's own configuration needs a standard stdio MCP server entry pointing at nexus-mcp.

For the hosted CLIs listed under Which CLI, NEXUS writes this entry for you automatically once the CLI is enabled and detected in NEXUS's AI Providers list — see Automatic wiring below. For every other MCP-compatible CLI, add the entry yourself using this page.

When you need this page

Running a command-line agent inside a NEXUS pane does not, by itself, connect that agent to the canvas_*/agent_* tools — it just gives it a shell. If everything you want the agent to do is expressible as shell commands, you can stop there. You need the steps on this page the moment the agent should read or draw on the canvas, or originate a mesh message — anything that goes through nexus-mcp rather than the shell.

The server entry

Every MCP-compatible CLI accepts a stdio server entry in roughly the same shape: a command to run, optional arguments, and an environment block. NEXUS's server is no different:

{
  "mcpServers": {
    "nexus": {
      "command": "<path to the NEXUS MCP launcher>",
      "args": [],
      "env": {}
    }
  }
}

The top-level key name (mcpServers above), and where this block lives on disk, are decided by whichever CLI you're configuring — consult that CLI's own documentation. The shape of the entry itself — a command, no required arguments, no required environment — is the same everywhere.

The credential is not part of the entry

Leave env empty. NEXUS does not read a loopback address or a capability token from an environment variable — it writes a per-session credential file to disk once a session is running, and a connecting CLI reads that file at connection time. See Paths & Credentials for exactly where that file lives, how it's named, and why a token never travels in the environment: an environment variable is inherited by every child process a session spawns, with no way to scope it back down afterward, while a file with owner-only permissions is only ever read by something explicitly pointed at it.

Treat the credential file as you would any bearer token. It is rewritten during normal operation and removed when the session closes — a client holding a reference to a session that has since ended will find nothing usable there, not a stale-but-working token.

Which CLI

NEXUS hosts several CLI coding agents from its own rail — among them Claude Code, Codex, Gemini CLI, and the Chainabit CLI — and any of them can also act as an MCP client of nexus-mcp once the entry above is present in its own configuration. The same stdio entry shape works for all of them, and for any other MCP-compatible CLI you connect that isn't hosted by NEXUS at all. Each product keeps its own configuration file and its own name for the top-level key — consult that product's own documentation for where the entry actually lives.

Automatic wiring

NEXUS writes the entry for you for these hosted CLIs, once each is enabled and detected in AI Providers: Claude Code, Codex, Gemini CLI, Cursor, Antigravity, Kimi Code, and OpenClaw. Every other CLI — including any not hosted by NEXUS at all — needs the manual steps on this page.

A few things follow from that:

• It's on by default, per CLI. Each of those provider's detail pages in AI Providers has its own "NEXUS MCP server" toggle if you'd rather manage that CLI's entry yourself, plus a live Connected / Not Connected status and a manual Reconnect action.
• Disabling a provider cleans up after itself. Turning a provider off (or turning off just its MCP toggle) removes the entry NEXUS wrote, rather than leaving a stale reference behind.
• It re-applies itself. If the entry disappears — you edited the CLI's config file by hand, for instance — NEXUS re-adds it the next time it starts.
• The path it fills in is nexus-mcp's own install location, which NEXUS also keeps current; you don't need to know or maintain that path yourself for an auto-wired CLI.

Verifying the connection

Once the entry is in place, start the CLI and make a discovery call. A response — rather than a hang or a connection refusal — tells you the entry is correct and which protocol era you're speaking. See Protocol Eras for what that call looks like in both eras this server supports, and Tool Namespaces for confirming the canvas_* and agent_* tools are present once you're connected.

A canvas tool call will still fail on its own terms even after a clean connection — no role is granted by default. See Canvas: Roles & Permissions.

Where to go next

• How to expose NEXUS to a CLI — the exact numbered steps, including the entitlement check and the two version-negotiation errors to handle.
• Connect a CLI — the first-time walkthrough.
• Paths & Credentials — the credential file's location, name, and permissions.
• MCP Protocol — the full transport and negotiation contract.