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)¶
- 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 atexamples/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 |