How to expose NEXUS to a CLI

Goal: point an MCP-compatible CLI coding agent at NEXUS's local MCP server so it can call the canvas_* and agent_* tools.

1. Confirm the entitlement

Check that the account has the MCP server and canvas entitlements before configuring anything:

curl -s https://<your-nexus-host>/api/v1/nexus/entitlements \
  -H "Authorization: Bearer $TOKEN" | grep -E '"nexus\.(mcp_sync|canvas)"'

If either key just changed, wait up to 300 seconds before treating a false as a real denial — see Entitlements.

2. Start a NEXUS workspace

tools/list is served live from a running workspace and fails closed with none running (see MCP Protocol). Start the workspace before configuring the CLI, not after.

3. Point the CLI at the server

For Claude Code, Codex, Gemini CLI, Cursor, Antigravity, Kimi Code, or OpenClaw, NEXUS does this step for you once the CLI is enabled and detected in AI Providers — see Automatic wiring. For any other CLI, add nexus-mcp to its MCP server configuration as a stdio server yourself. Most MCP-compatible CLIs accept a configuration block along these lines:

{
  "mcpServers": {
    "nexus": {
      "command": "nexus-mcp",
      "args": [],
      "env": {}
    }
  }
}

Do not put a capability token in env — NEXUS's credential files are read from disk, not from the environment, and environment variables are inherited by every child process the session spawns. See Paths & Credentials.

4. Let the client negotiate a protocol version

A client built against a current MCP SDK typically negotiates the version automatically. If you are hand-rolling the transport, see MCP Protocol for the exact handshake — either the legacy initialize exchange or the _meta-based 2026-07-28 style — and for the -32022 error returned when the requested version isn't supported.

5. Verify the tools appear

Call tools/list and confirm the canvas_* and agent_* tools are present:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

An empty or missing tool set here usually means step 2 was skipped — start the workspace and retry.

6. Grant the agent a canvas role

There is no default canvas role. Before the connected agent can read or write a canvas, grant it a role explicitly — see Canvas Roles. A call made with no grant returns a clear error rather than doing nothing silently, so this is easy to catch early.

7. Handle the two version-negotiation errors

Whatever client you connect, be ready to handle:

• -32022 — the requested protocol version isn't supported; data.supported lists what is.
• -32602 — _meta engaged the io.modelcontextprotocol/ namespace without a valid protocolVersion.

Both are detailed with example payloads in MCP Protocol.