Skip to content

Using NAVIGATOR from Claude Code

NAVIGATOR is an independent MCP server. Any MCP host can use it; this guide uses Claude Code (the CLI, or the Code tab of the Claude desktop app) on a Windows or Linux PC, with NAVIGATOR running on the Linux host that holds the inventories (here navhost). No Hermes, no Slack chat bot: you talk to Claude Code, and Claude Code calls NAVIGATOR's tools. Approvals still happen on the approval channel. Test cases: TESTING_CLAUDE_CODE.md.

1. MCP in five minutes

Word Meaning here
MCP (Model Context Protocol) An open standard that lets an AI assistant use outside tools. The assistant does not run your scripts; it asks a server to run a named tool with arguments, and gets JSON back
MCP server A program that offers tools. NAVIGATOR is one (navigator-mcp): 16 tools such as inventory, device, change, project
MCP host (client) The AI app that connects to servers and lets the model call their tools: Claude Code, Cursor, Hermes, OpenClaw…
Tool One named action with a schema, e.g. device with action=read, inventory=EVPN_LAB, commands=[...]. The model picks the tool and arguments from your request; you see each call
stdio transport The host starts the server as a child process and they exchange JSON messages over its standard input and output. No port, no web server. NAVIGATOR uses stdio
Server instructions Text the server gives the host on connect (NAVIGATOR's rules: no secrets, approvals out of band, LOCKED projects…). The model reads them before using the tools

What happens when you type "show bgp summary on the spines in EVPN_LAB":

 You ──▶ Claude Code (host, the model decides) ──tool call: device read──▶ NAVIGATOR (server, on navhost)
                                                                              │ ATLAS: which devices, which credential
                                                                              │ RUDDER: connect, run allowed commands
 You ◀── answer with the outputs ◀── JSON result (outputs + record file) ◀────┘

Claude Code asks your permission the first time it calls each tool (you can allow it once or always). Reads need no ticket. Changes become a RUDDER ticket and wait for a human !pushok on the approval channel: Claude Code cannot approve, exactly like the chat bot.

2. How Claude Code reaches NAVIGATOR on another machine

Claude Code starts the server as a process. NAVIGATOR lives on navhost, so the "process" is an SSH command that starts navigator-mcp on navhost; stdio flows through the SSH connection. Nothing to install on the PC except Claude Code and an SSH client, and no port to open.

 PC: Claude Code ──starts──▶ ssh -T navhost "navigator-mcp" ══ SSH ══▶ navhost: navigator-mcp ─▶ ATLAS / RUDDER ─▶ devices
                   stdin/stdout (JSON-RPC) flow through the SSH session

Needs: ssh navhost works from the PC without a password prompt (key auth; an navhost entry in ~/.ssh/config). Check in a terminal: ssh -o BatchMode=yes navhost echo ok must print ok.

3. Set it up (5 minutes)

  1. Make a folder for the test, e.g. SRISPACE\NAVIGATOR\cc-test, and put this file in it as .mcp.json (a project-scoped MCP config; a copy is in the repo at examples/claude-code/.mcp.json):

{
  "mcpServers": {
    "navigator": {
      "type": "stdio",
      "command": "ssh",
      "args": ["-T", "-o", "BatchMode=yes", "navhost",
               "NAVIGATOR_BOOTSTRAP=/home/<user>/.config/navigator/navigator.yml exec /home/<user>/navigator/.venv/bin/navigator-mcp 2>/dev/null"]
    }
  }
}
- -T: no terminal; the channel carries only the JSON messages. - BatchMode=yes: never stop at a password prompt (it would hang the host). - NAVIGATOR_BOOTSTRAP: NAVIGATOR's settings file on navhost (the same one the chat bot uses, so the same inventories, projects and approval channel). - 2>/dev/null: the server's log lines stay out of the protocol stream. 2. Open that folder in Claude Code: claude in a terminal inside it, or the Code tab with that folder. Claude Code asks whether to trust the project's MCP server navigator: say yes. 3. Type /mcp. navigator must show connected with 16 tools. If not, see section 6. 4. Ask: "which navigator tools do you have?"

Instead of a .mcp.json, the same server can be added for every folder with claude mcp add navigator --scope user -- ssh -T -o BatchMode=yes navhost "NAVIGATOR_BOOTSTRAP=… exec …/navigator-mcp 2>/dev/null". On a machine that has the repo itself, the command is just navigator-mcp with the NAVIGATOR_BOOTSTRAP environment variable.

Cursor works the same way: put the same mcpServers block in .cursor/mcp.json (project) or ~/.cursor/mcp.json (all projects), then check Settings → MCP.

4. Using it

Talk normally; NAVIGATOR's instructions tell the model which tool fits. Examples (more in CHEATSHEET.md):

You say Tool call
"list inventories" inventory action=list
"show bgp summary on the spines in EVPN_LAB" device action=read groups=[SPINE] commands=[...]
"add interface Loopback96 on LEAF1A with description cc-test" change action=propose → a ticket, a request in #approvals
"status of ticket C…?" change action=status
"changes on LEAF1A today" change action=list since=… device=LEAF1A
"new OPEN project CC_TEST with ticket CHG0012345: lab check" project action=create ticket_id=CHG0012345
"create a new inventory CC_LAB" inventory_edit interview: questions → preview → your yes → commit

Differences from the Hermes chat bot: - Results come back when you ask. Claude Code has no thread for RUDDER to post into (reply_to is a Hermes plugin), so after your !pushok the result appears in #approvals; ask Claude Code for the ticket's status to see it there too. - "Requested by" shows the consumer (NAVI), not your Slack name: Claude Code does not fill requested_by. Because of that, SHIP engineer bypass never applies from Claude Code. - Claude Code has its own shell. NAVIGATOR's rules do not limit what Claude Code itself may run on your PC. Say no if it ever asks to read ~/.hermes/push-approvals, ticket files or the private data folder over SSH: approvals and credentials are human-only.

5. The two interviews

Host setup (navigator-setup): on navhost in a terminal (it asks questions, so not from inside Claude Code): PROJECT_ROOT (checked: exists, writable), SKILLS_ROOT (checked: readable, has skills), approval method and its details (a test code must be approved before anything is saved). To try it without touching the live settings, point it at scratch files:

ssh -t navhost
export NAVIGATOR_BOOTSTRAP=/tmp/cc-navigator.yml RUDDER_LOCAL=/tmp/cc-rudder.local.yml
~/navigator/.venv/bin/navigator-setup          # the interview
~/navigator/.venv/bin/navigator-setup show
rm -f /tmp/cc-navigator.yml* /tmp/cc-rudder.local.yml*      # clean up

Inventory interview (inventory_edit): from Claude Code. Every change to an inventory goes: start → the model asks you the returned questions → your answers → preview → your yes → commit with the preview's code. Nothing is written before the commit. Passwords are never asked in chat: for a credential the model tells you to run atlas-interview secret <draft> LOGIN_PASSWORD on navhost. Who may use a new inventory (consumer_access) is host-only: atlas-interview run consumer_access --consumer NAVI on navhost.

6. Running the AI on Google Vertex AI (Claude Code or Gemini CLI)

To bill the model to a Google Cloud project instead of a Claude subscription, run the CLI on the NAVIGATOR host with a Vertex AI service account. Two options; both use NAVIGATOR the same way (stdio, no SSH):

Claude Code on Vertex Gemini CLI on Vertex
Models Claude models enabled in Vertex Model Garden for the project. Claude Code cannot run Gemini Gemini models
Install npm install -g @anthropic-ai/claude-code npm install -g @google/gemini-cli
Vertex switches CLAUDE_CODE_USE_VERTEX=1, ANTHROPIC_VERTEX_PROJECT_ID=<project>, CLOUD_ML_REGION=<region> GOOGLE_GENAI_USE_VERTEXAI=true, GOOGLE_CLOUD_PROJECT=<project>, GOOGLE_CLOUD_LOCATION=<region>
Credentials GOOGLE_APPLICATION_CREDENTIALS=<service-account JSON> (both) same
NAVIGATOR config .mcp.json in the test folder: command = …/.venv/bin/navigator-mcp, env.NAVIGATOR_BOOTSTRAP .gemini/settings.json → mcpServers.navigator (same command and env)
Keep it NAVIGATOR-only .claude/settings.json → permissions.deny: Bash, Edit, Write, WebFetch, WebSearch, Read(//<secrets and approval folders>/**) .gemini/settings.json → excludeTools: shell, file and web tools
Check /status (Vertex AI, project), /mcp (16 tools) /mcp (navigator Ready), /tools (only navigator)

Why NAVIGATOR-only: on the NAVIGATOR host the CLI would otherwise have a shell next to the credential store and the approval files. An AI tool must never be able to read an approval code or a credential. Deny the built-in shell, file and web tools and the folders with secrets and approvals; NAVIGATOR's own tools are all it needs for these tests.

On navhost the full, copy-ready steps are in ~/NAVIGATOR_VERTEX_TEST.txt (project, region and the path to the existing service-account file filled in; no key in the file).

7. Troubleshooting

Symptom Fix
/mcp shows failed or connecting forever In a terminal on the PC: ssh -o BatchMode=yes navhost echo ok. A password prompt or host-key question means key auth or known_hosts is not set up
Connected but 0 tools / "invalid JSON" Something printed to stdout before the protocol started: keep -T and 2>/dev/null; no echo in navhost's .bashrc for non-interactive shells
Tools work but "no inventory" / "not found" NAVIGATOR_BOOTSTRAP points to the wrong file, or the consumer has no access (atlas-interview run consumer_access)
A change waits forever Approve it in #approvals with !pushok CODE; Claude Code never gets the code
Slow first call The first device call opens the ATLAS link and logs in to the device (eAPI ~0.1 s, SSH ~3 s, pyATS longer)
Vertex: "model not found / not enabled" Claude Code: enable the Claude model in Vertex Model Garden for that project and region (or set ANTHROPIC_MODEL); Gemini CLI: check GOOGLE_CLOUD_LOCATION
Vertex: permission denied The service account needs the Vertex AI User role on the project; GOOGLE_APPLICATION_CREDENTIALS must point at its JSON