Repository navigation
docs: day-to-day Claude Code setup (closes #9) - #18
Conversation
Replaces the generic SSH-tunnel section with the exact flow proven end-to-end against a real device: master socket carrying the tunnel (one auth), the dropbear agent-flood gotcha, tunnel liveness check, token-to-file with by-reference usage everywhere, and fresh-session pickup. Durable access is #16; other MCP clients are #17. Closes #9. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
Warning Review limit reached
Next review available in: 51 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. 📝 WalkthroughWalkthroughThe README replaces one-off SSH forwarding instructions with a tested workflow using a persistent SSH master connection, protected MCP token retrieval, Claude Code registration, session guidance, and MCP Inspector verification. ChangesClaude Code SSH setup
Estimated code review effort: 1 (Trivial) | ~3 minutes 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@README.md`:
- Around line 211-218: Update the README token retrieval command to handle an
unset NANOKVM_MCP_TOKEN by extracting the auto-generated token from daemon.log
or reporting a clear error, rather than creating an empty token file. Write the
result to a temporary file with 0600 permissions, validate that a non-empty
token was obtained, then atomically rename it to ~/.nanokvm-token.
- Around line 185-191: Update the SSH tunnel documentation around the “Claude
Code over an SSH tunnel” section to describe ControlPersist=3600 as an idle
timeout: the master connection remains active beyond one hour when reused, and
exits only after 3600 seconds without connections. Apply the same clarification
to the related text in the setup flow.
- Around line 196-199: Update the SSH command in the README to include the
ExitOnForwardFailure=yes option alongside the existing SSH options, ensuring ssh
-f only backgrounds after the local port forward is successfully established.
- Around line 237-242: Update the MCP Inspector example near the tools/list
invocation to avoid interpolating NANOKVM_MCP_TOKEN into command-line arguments.
Use a supported file/config-based header mechanism, or replace the command with
a documented non-CLI validation method that does not expose the bearer token
through process arguments.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| To sanity-check the endpoint without Claude, use MCP Inspector: | ||
|
|
||
| ```sh | ||
| npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8080/ \ | ||
| --transport http --header "Authorization: Bearer ${NANOKVM_MCP_TOKEN}" --method tools/list | ||
| ``` |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Show the relevant README section with line numbers
sed -n '220,255p' README.md
# Find other Inspector references in the repo
rg -n "modelcontextprotocol/inspector|MCP Inspector|NANOKVM_MCP_TOKEN|Authorization: Bearer" -S .Repository: tylervick/nanokvm-mcp
Length of output: 5632
🌐 Web query:
@modelcontextprotocol/inspector CLI --header file stdin environment variable bearer token documentation
💡 Result:
The @modelcontextprotocol/inspector CLI supports custom HTTP headers, including bearer tokens, through the --header flag [1][2]. When using the CLI mode, you can pass authentication credentials by providing the header directly in the command [3][4]. The format requires the header name and value, typically structured as an Authorization header for bearer tokens [2][3]. Usage example: npx @modelcontextprotocol/inspector --cli https://example.com/mcp --transport http --method tools/list --header "Authorization: Bearer YOUR_TOKEN" Key details regarding this functionality: - Multiple --header flags: You can pass multiple --header flags in a single command if needed [2]. - Format: The argument must follow the "HeaderName: Value" format [1][2]. - Transport Compatibility: The headers are passed to both HTTP and SSE transports [2]. - Environment Variables: While the CLI supports the --header flag for ad-hoc requests, environment variables are not a native, direct configuration mechanism for header injection in the Inspector CLI itself; you should inject the variable into the command string (e.g., --header "Authorization: Bearer ${MY_TOKEN}") [2][4]. - Limitations: There have been reports that in some scenarios, specifically involving the Inspector's own proxy mechanisms, custom headers might be misinterpreted or overwritten if they conflict with internal authentication headers [5][6]. Ensure your header names do not conflict with reserved proxy headers if you are experiencing connectivity issues [6]. For standard testing, using the --header flag as shown above is the official and recommended method for providing bearer tokens to remote MCP servers via the Inspector CLI [2][3].
Citations:
- 1: https://github.com/modelcontextprotocol/inspector?tab=readme-ov-file
- 2: Add support for --header flags in MCP Inspector CLI modelcontextprotocol/inspector#716
- 3: https://developers.bookingsync.com/guides/mcp/testing-with-mcp-inspector
- 4: https://ubos.tech/mcp/remote-mcp-server-with-bearer-auth/
- 5: MCP Inspector Cannot Pass Custom Authentication Headers modelcontextprotocol/inspector#879
- 6: v0.14.1 Bearer Token overwritten by Proxy Session Token modelcontextprotocol/inspector#508
🌐 Web query:
@modelcontextprotocol/inspector README --header stdin file environment variable inspector cli auth bearer token
💡 Result:
The @modelcontextprotocol/inspector is a developer tool used for testing and debugging MCP servers [1][2]. It provides a CLI mode, a web-based UI, and a Terminal UI (TUI), all executable via npx [3][4]. Regarding your specific areas of interest: Environment Variables and Auth For authentication, particularly when running in containerized environments, you can manage tokens using environment variables [5]: - MCP_INSPECTOR_API_TOKEN: Use this to set a known bearer token for the inspector [5]. If not set, one is automatically generated and displayed in the logs [5]. - DANGEROUSLY_OMIT_AUTH: Set this to true to disable authentication entirely [5][6]. - DANGEROUSLY_BIND_ALL_INTERFACES: Set this to true if you need to bind the inspector to 0.0.0.0, which is otherwise refused by default for security reasons [5]. CLI and Bearer Tokens - CLI Mode: The CLI allows for programmatic interaction with MCP servers (e.g., npx @modelcontextprotocol/inspector --cli ) [3][7]. - Bearer Tokens in UI: When using the web UI to connect to remote servers (e.g., SSE transport), you can provide a bearer token in the sidebar [7]. The inspector includes this in the Authorization header [7]. Note that there have been reports of the proxy session token potentially overwriting the Authorization header if they share the same name [6]; users are advised to use a different header name or set DANGEROUSLY_OMIT_AUTH if conflicts arise [6]. Stdin/File Configuration - The inspector supports configuring servers via command-line arguments or configuration files [1][3]. You can use --config to point to a configuration file that defines server launch commands, environment variables, and other parameters [1][7]. - When inspecting locally developed servers, the tool can be invoked with the server's command directly in the CLI, or by using a config file to manage multiple server definitions [1][7]. Detailed documentation on server configuration (including catalog vs. config files and per-server fields) is available in the project's docs/ directory [3].
Citations:
- 1: https://modelcontextprotocol.io/docs/tools/inspector
- 2: https://github.com/modelcontextprotocol/inspector?tab=readme-ov-file
- 3: https://github.com/modelcontextprotocol/inspector
- 4: https://www.npmjs.com/package/@modelcontextprotocol/inspector
- 5: https://github.com/modelcontextprotocol/inspector/blob/main/README.md
- 6: v0.14.1 Bearer Token overwritten by Proxy Session Token modelcontextprotocol/inspector#508
- 7: https://github.com/modelcontextprotocol/inspector/blob/24e8861a88f843d57cdb637a5ae3afd0e528c5f3/README.md
🌐 Web query:
@modelcontextprotocol/inspector config headers authorization bearer token --config
💡 Result:
To configure an authorization bearer token in the Model Context Protocol (MCP) Inspector, you can use the web interface or command-line arguments depending on your setup. Web Interface Configuration The Inspector UI allows you to add custom headers to your connection settings to support bearer token authentication [1][2][3]. 1. Open the MCP Inspector interface [4][5]. 2. Click the Configuration button (or "Add Header" in the connection setup area) [6][7][2]. 3. Add a new header entry [2]. 4. Set the Header field to Authorization and the Value field to Bearer YOUR_TOKEN [2][3]. Recent updates have enhanced header management, allowing for multiple custom headers and flexible configurations [1]. The UI now supports both form-based and JSON editor modes for these headers [1]. These settings are stored in your browser's local storage for persistence between sessions [8][3]. Command-Line Configuration When starting the Inspector from the command line, you can pass custom headers directly using the --header argument [6][9]. Example command: npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com --transport http --header "Authorization: Bearer your-api-key" Proxy Authentication If you are running the MCP Inspector proxy, note that it requires its own authentication by default [6][10]. A session token is generated when the proxy starts and is printed to the console [6][4]. This token must be included as a Bearer token in the Authorization header for all requests to the proxy server [6][10]. You can also specify this token using the MCP_PROXY_AUTH_TOKEN environment variable when starting the server [6][4][10]. Top Results: [6], [1], [2], [3], [5]
Citations:
- 1: Add support for custom headers and migrate from legacy auth modelcontextprotocol/inspector#751
- 2: https://docs.getmcp.com/docs/guides/mcp-inspector
- 3: https://docs.mcp-use.com/inspector/connection-settings
- 4: https://github.com/modelcontextprotocol/inspector/blob/dd53302e12e6342072fadb2a759afb5a6648696b/README.md
- 5: https://github.com/jmorrell-cloudflare/mcp-bearer-auth-example
- 6: https://github.com/modelcontextprotocol/inspector/blob/19e12e20/README.md
- 7: Enable Authentication header name configuration modelcontextprotocol/inspector#272
- 8: Add Bearer Token Support modelcontextprotocol/inspector#175
- 9: https://github.com/modelcontextprotocol/inspector?tab=readme-ov-file
- 10: https://deepwiki.com/modelcontextprotocol/inspector/4-proxy-server
Avoid interpolating the token in the Inspector CLI example. Shell expansion puts ${NANOKVM_MCP_TOKEN} into the spawned process’s argv, so the bearer token is exposed to ps/local users. Use a file/config-based header path if this Inspector release supports one, or document a non-CLI check instead.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@README.md` around lines 237 - 242, Update the MCP Inspector example near the
tools/list invocation to avoid interpolating NANOKVM_MCP_TOKEN into command-line
arguments. Use a supported file/config-based header mechanism, or replace the
command with a documented non-CLI validation method that does not expose the
bearer token through process arguments.
There was a problem hiding this comment.
Caveat added in 5f6613c rather than restructuring: per your own research above, Inspector has no file/config-based header mechanism — --header interpolation is its official method — and the primary flow (claude mcp add) already keeps the secret out of argv via the unexpanded ${VAR}. The note flags the ps exposure and points shared-host users at curl's @file header form.
…ken-file hardening - ControlPersist=3600 described as an idle timeout, not a 1-hour cap - ExitOnForwardFailure=yes so a failed -L bind fails loudly instead of backgrounding a broken master - token pull: umask 077 subshell (no permissive window) + test -s guard for the unset-token path - note that the Inspector CLI example exposes the token to ps (no file-based header exists in Inspector); curl @file suggested for shared hosts Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 participant
Summary
Documents the Claude Code connection flow exactly as validated today against real hardware (v0.1.0 release binary, read-only mode): SSH master socket + tunnel with one auth, the dropbear agent-flood workaround discovered during setup, tunnel liveness check, bearer token pulled to a file and used by reference everywhere,
claude mcp addwith unexpanded${VAR}, and fresh-session pickup.Scoped to Claude Code per discussion — durable access is #16, Claude Desktop and other clients are #17.
Closes #9.
🤖 Generated with Claude Code