Connect a CLI over MCP

Every session so far in this path has been a CLI agent NEXUS launched for you, inside its own terminal, configured from AI Providers in the rail. This page covers the other direction: an already-running CLI agent — inside NEXUS or entirely outside it — connecting back to NEXUS as an MCP client, to call the canvas and mesh tools covered in the Guides. Most day-to-day use of NEXUS never needs this page; it matters once you're building against NEXUS's protocol surface.

NEXUS's local MCP server is declared to a CLI the same way any stdio MCP server is: a standard entry naming a command to run and, optionally, an environment for it. The exact configuration keys depend on which CLI you are configuring — Claude Code, Codex, Gemini CLI, and the Chainabit CLI each read their own list of MCP servers from their own configuration file — but the shape is the same for all of them:

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

Consult your CLI's own documentation for where that entry lives and what it calls the top-level key (mcpServers above is illustrative of the shape, not a NEXUS-specific requirement).

The credential is not an environment variable

Do not put a loopback address or a token in the env block above — NEXUS does not read either from the environment. Instead, once NEXUS is running, it writes a per-session credential file containing the loopback address and the capability token a session needs. See Paths for exactly where that file lives. A connecting CLI (or a thin wrapper you write around it) reads the file at session start.

Treat the credential file the way you would treat any bearer token: it is session-scoped, and anything with read access to it can act as that session.

Verify the connection

Once the entry is in place and NEXUS is running, start the CLI and make a discovery call — the response tells you the connection is live and which protocol revision you are speaking.

Next

First tool call — send a real request and read the exact response back.