Install Hadron in Claude Code¶

This guide covers the OAuth-based install path for Claude Code: paste the Hadron MCP URL, sign in once via your browser, and Claude Code has access to your Hadron memories — with the option to use CLAUDE.md to pin a specific Hadron App per project so multi-App users skip the per-session selection step.

For the AppKey-based path (download a config file from the portal's Client tab), see Connecting an MCP host to Hadron. OAuth is the recommended path for interactive Claude Code sessions because each issued token is tied to a clear audit-trail row in your portal API-keys page — one click to disconnect.

What you'll have at the end¶

A hadron MCP server registered in Claude Code with the h-* tools available.
A row in your portal API-keys page with a source badge reading OAuth: dcr_…<client> — the token Claude Code is using.
(Optional, multi-App users) A CLAUDE.md entry in your project root that auto-pins one Hadron App per project, so Claude Code doesn't have to ask you which App to use each session.

What you need¶

A Hadron portal account at hadronmemory.com.
Claude Code installed (npm install -g @anthropic-ai/claude-code or the install method documented at docs.claude.com/claude-code).
For local development only: cloudflared (Homebrew: brew install cloudflared) + a running local hadron-server.

Production install¶

In a terminal, run:

claude mcp add --transport http hadron https://srv.hadronmemory.com/mcp

Start Claude Code in any project directory:
```
cd ~/my-project
claude
```
The first Hadron tool call (or any explicit OAuth trigger) opens a browser window to Hadron's sign-in page. Claude Code's OAuth client handles the PKCE dance, Dynamic Client Registration, and consent automatically.
Sign in via GitHub if you haven't already; review the consent screen — it shows the client name ("Claude Code"), the scope (mcp), and the resource (Hadron's MCP endpoint).
Click Approve. Claude Code stores the access token and is now connected.

Test it: in the Claude Code REPL, type "List my Hadron memories." Claude calls h-list-memories and prints the result.

Local development install (`cloudflared` tunnel)¶

For testing changes against a local hadron-server, Claude Code needs an HTTPS URL. Cloudflare's free quick-tunnel service does this with no signup.

1. Start the server¶

In one terminal:

cd hadron-server
pnpm dev
# Server listens on http://localhost:4000

2. Open the tunnel¶

cloudflared tunnel --url http://localhost:4000
# Copy the printed https://<random>.trycloudflare.com URL

3. Register the local server in Claude Code¶

claude mcp add --transport http hadron-local https://<random>.trycloudflare.com/mcp

Use a distinct name like hadron-local to keep it separate from the production registration.

4. Verify¶

Run claude and ask it to list your Hadron memories. Confirm tools appear under the hadron-local server.

Multi-App users — pin an App per project via `CLAUDE.md`¶

If your Hadron account is a member of more than one App, Claude Code needs to know which one this project belongs to. Single-App users skip this section — the lone App resolves automatically.

The `CLAUDE.md` pattern¶

Claude Code loads any CLAUDE.md file in the project root (or parent directories) as system instructions for every session in that directory. Add a Hadron-App-pinning instruction:

# Project context

This project uses the Hadron App
`hrn:app:<your-org>::<your-app>`. Before using any Hadron tool,
call `h-set-active-app` with that URN.

Replace the URN placeholder with one of your actual App URNs. To see your options, run claude in any directory once and ask "List my Hadron apps." — Claude calls h-list-apps and prints the URNs.

After the CLAUDE.md change, the next Claude Code session in this directory:

Reads CLAUDE.md at startup.
Sees the App-pinning instruction.
Calls h-set-active-app with the URN as its first Hadron tool call.
Subsequent tool calls (h-find-nodes, h-add-node, etc.) resolve against the pinned App automatically.

You can override the pinned App mid-session by asking "switch to my Acme App" — Claude calls h-set-active-app again with the new App.

What happens without `CLAUDE.md`¶

Multi-App users without a CLAUDE.md pin can still work — Claude will call h-list-apps and ask which App to use the first time it needs an App context. But it's friction per session.

Single-App users see no difference either way: spec 025's single-App default resolves automatically without h-set-active-app.

What you'll see if a tool needs an App and none is active¶

If Claude calls a chat-style tool (h-chat-start, h-chat-send, or h-start-session) before any App is selected, the server returns:

[no_active_app] No active Hadron App. Call h-list-apps to see
options, then h-set-active-app with the one you want. If you're
calling from a project directory, set `app` in `.hadron/config.json`.

Claude typically recovers by calling h-list-apps + h-set-active-app and retrying. Read tools (h-list-memories, h-find-nodes, h-read-node) work without selection — they return results across every App you can access, since App identity in Hadron is a focusing concern, not access control. See Authentication for the architectural rationale.

Verifying + revoking¶

Each successful OAuth install creates a row on your API keys page in the Hadron portal with a source badge like OAuth: dcr_abc123…. The suffix after OAuth: is the client identifier Claude Code registered.

To disconnect Claude Code:

Open the portal → Account → API keys (sidebar).
Find the row with the matching OAuth: source badge.
Click Revoke → confirm.

The next Hadron tool call from Claude Code returns 401 Unauthorized and Claude Code will prompt you to re-authenticate.

Troubleshooting¶

`claude mcp add` says the server already exists¶

Use claude mcp list to see registered servers and claude mcp remove <name> to clear an old registration before re-adding.

Browser never opens for OAuth¶

Claude Code typically uses the system default browser. If the window doesn't appear, check the Claude Code log for the OAuth URL and open it manually:

claude --log-level debug

The OAuth-authorize URL is printed when the dance starts.

Multi-App `CLAUDE.md` pin doesn't apply on the first call¶

Claude Code reads CLAUDE.md at session start, but the LLM has discretion over when to follow the instruction. If you notice the first Hadron tool call skipping the h-set-active-app step, make the instruction more emphatic (e.g., capitalize MUST in the sentence). The reliability of instruction-following improves with explicit phrasing.

For a more robust pinning mechanism (server-side App pinning via .hadron/config.json without instruction-following), watch for the directory-aware regime (b) follow-up in a future spec — it will let clients send the App URN in the MCP initialize handshake directly, removing the LLM-as-parser dependency.