Install Hadron in Claude Desktop¶

This guide covers the OAuth-based install path: you paste Hadron's MCP URL into Claude Desktop, sign in through your browser, click Approve on a consent screen, and Claude Desktop has access to your Hadron memories. No copy-paste of API keys; the OAuth flow handles it.

Two scenarios are covered:

Production — point Claude Desktop at the public Hadron URL.
Local development — use cloudflared to expose a local hadron-server so the OAuth flow can complete (Claude Desktop's browser-side OAuth client requires HTTPS).

For the older AppKey-based install (download a config file with a baked-in key), see Connecting an MCP host to Hadron. That path still works for AppKey-compatible hosts; OAuth is the recommended path for Claude Desktop because the consent screen ties each issued token to a clear "this app was granted access on <date>" audit trail you can revoke in the portal.

What you'll have at the end¶

Hadron listed as a Connector in Claude Desktop with h-* tools available.
A row in your portal API-keys page with a source badge reading OAuth: dcr_…<client>. This is the token Claude Desktop is using; revoking it here immediately disconnects Claude Desktop.

What you need¶

A Hadron portal account at hadronmemory.com.
Claude Desktop installed.
For local development only: cloudflared (Homebrew: brew install cloudflared) and a running local hadron-server.

Production install¶

Open Claude Desktop → Settings → Connectors → Add Custom Connector.
Paste the Hadron MCP URL: https://srv.hadronmemory.com/mcp.
Claude Desktop performs the OAuth discovery handshake automatically:
Fetches the Protected Resource Metadata (/.well-known/oauth-protected-resource).
Fetches the Authorization Server metadata (/.well-known/oauth-authorization-server).
Registers itself dynamically (RFC 7591 DCR) at /oauth/register — no manual client setup.
A browser window opens to Hadron's sign-in page. If you're already signed in via GitHub, you'll see the consent screen directly; otherwise sign in first.
Review the consent screen — it shows the client name ("Claude Desktop"), the scope (mcp), and the resource (Hadron's MCP endpoint).
Click Approve.
Claude Desktop redeems the authorization code for an access token and stores it locally.
Hadron appears in Claude Desktop's Connector list with the h-* tools listed.

Test it: ask Claude something like "Can you list my Hadron memories?" — if the tools are wired up, Claude will call h-list-memories and show you a list.

Local development install (`cloudflared` tunnel)¶

For testing changes against a local hadron-server, Claude Desktop needs an HTTPS URL to talk to. 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¶

In a second terminal:

cloudflared tunnel --url http://localhost:4000

Cloudflare prints an https://<random>.trycloudflare.com URL in the output. Copy it. (The URL changes each time you restart the tunnel.)

3. Point Claude Desktop at the tunnel¶

In Claude Desktop → Settings → Connectors → Add Custom Connector → paste https://<random>.trycloudflare.com/mcp.

The OAuth dance runs the same way as in the production install. The sign-in browser window opens against the tunnel URL.

4. Verify¶

Confirm the tools appear under the Connector and that you can trigger h-list-memories in chat.

Multi-App users — pick an App for each chat¶

If your Hadron account is a member of more than one App (for example "Acme Mealplan" and "Mentor Co Juno"), Claude Desktop opens the session successfully but no App is the active focus yet. Two new tools handle the selection:

h-list-apps — shows the Apps your account can access, with each one's URN, display name, and your role.
h-set-active-app — pins one App as the active scope for the rest of the MCP session. Subsequent App-scoped tool calls (h-chat-start, h-chat-send, h-start-session, etc.) resolve to that App.

The flow, by hand¶

Typical first conversation:

You: What Hadron Apps do I have access to?

Claude: (calls h-list-apps) You have access to:

hrn:app:acme-corp::mealplan — Acme Mealplan (role: cook)

hrn:app:mentor-co::juno — Mentor Co Juno (role: principal)

You: Set the active App to Mentor Co Juno.

Claude: (calls h-set-active-app with the URN) Active App set to hrn:app:mentor-co::juno (Mentor Co Juno). Subsequent App-scoped tools will operate against this App.

You: Find nodes about onboarding.

Claude: (calls h-find-nodes — now scoped to Mentor Co Juno) …

You can switch Apps mid-conversation by calling h-set-active-app again with a different identifier. The selection is per-session — when the MCP session closes (you disconnect the connector, restart Claude Desktop, etc.), the selection is cleared and you re-pick on next use.

The selector tools also accept App display names directly when they match unambiguously — Set the active App to "Mentor Co Juno" works when no other accessible App shares that name. If two Apps share a name across orgs, the server returns a typed disambiguation error listing the URN candidates, and you re-issue the selection with the URN form.

If you have exactly one App, you don't need any of this — Hadron resolves to your single App automatically (single-App default, unchanged from prior behavior). The h-list-apps and h-set-active-app tools still appear in the tool list, but you don't need to call them.

Skip the friction with a Claude Desktop Project¶

Claude Desktop Projects carry a system prompt that's injected into every chat in the project. Adding the App-selection instruction there means Claude does it automatically on every new chat — no manual ask required.

Open Claude Desktop → Projects → New Project.
Add Hadron as a connector if you haven't already (one-time per install).

In the project's system prompt, paste something like:

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 (call h-list-apps once in any chat to see your options).

Every new chat under that project starts with the right App in scope. Different projects can pin different Apps.

Read tools work without selection¶

Tools that read data (h-list-memories, h-find-nodes, h-read-node, etc.) succeed even when no App is active — they return results across every App you can access. App identity in Hadron is a focusing concern, not access control: selecting narrows the view rather than gating access. See Authentication for the architectural rationale (constitution Article V — Zero-Trust Apps).

A small set of strict tools that genuinely need App context to function (h-start-session, h-end-session, all h-chat-* tools) DO require an active App and return one of the errors below if none is set.

Common multi-App errors¶

If a strict tool runs before you've selected an App, Claude will surface one of these messages:

Message starts with	What it means
`[no_active_app] No active Hadron App…`	You've engaged with the selection surface (called `h-list-apps` already, or your client sent the directory-aware `initialize` parameter) but haven't pinned an App. Call `h-set-active-app` with an App URN or name.
`[multiple_apps_resolved] User has more than one Hadron App…`	FR-016 fall-through for the first strict-tool call before the session has touched the new selection surface. Same recovery — call `h-list-apps` then `h-set-active-app`. The literal `multiple_apps_resolved` token is preserved verbatim so production-log greps continue to match (SC-003).
`[app_identifier_ambiguous] Multiple Apps match…`	You passed a short name that matches 2+ Apps. The error lists the matching URNs; retry with one.
`[app_not_found] No accessible App matches…`	The identifier doesn't match any App you can access. Use `h-list-apps` to see what's available.
`[app_unavailable] App … is no longer available`	The App was uninstalled or deleted. Pick another.
`[app_member_revoked] Your access to App … has been revoked`	Your `AppMember` row was removed since the session started. The active selection is cleared; re-pick or contact the App owner.

See MCP App selection for the full tool reference.

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 Desktop registered.

To disconnect Claude Desktop:

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

The next time Claude Desktop tries to use that token, the /mcp endpoint returns 401 Unauthorized and Claude Desktop's UI will prompt you to re-authenticate. Until then, the connector is visible in Claude Desktop's UI but non-functional.

Troubleshooting¶

Claude Desktop never opens the OAuth browser window¶

The most common cause is a malformed Authorization Server metadata response. Manually fetch the AS metadata to inspect:

curl -s https://srv.hadronmemory.com/.well-known/oauth-authorization-server | jq

(If you don't have jq installed, drop the | jq and the response will print as a single line of JSON — readable, just not pretty-printed.)

Look for these two fields specifically:

registration_endpoint — must be present. Claude Desktop's backend silently bails if DCR isn't advertised.
token_endpoint_auth_methods_supported — must include "none". Spec-compliant clients otherwise expect a client secret that public clients can't supply.

For local-dev installs, also confirm the cloudflared tunnel is up (curl https://<random>.trycloudflare.com/.well-known/oauth-authorization-server).

"Failed to fetch" or HTTPS errors in the browser window¶

Local-dev only: Hadron's discovery URLs include the request's origin (scheme + host). If they come back as http:// instead of https://, the server's trust-proxy config can't see Cloudflare's X-Forwarded-Proto: https header.

For local development, app.set('trust proxy', true) (the dev default) is sufficient. For production this is locked to Cloudflare's IP-range list — see the server's src/auth/cloudflare-ips.ts for the boot-time fetch.

The client name is what Claude Desktop sent in the DCR request. If it reads "Unnamed MCP Client", Claude Desktop sent an empty client_name. There's no fix from the Hadron side; the next minor Claude Desktop release usually addresses this.

Approve button does nothing / CSRF errors¶

Check that cookies are enabled for the Hadron domain in the browser window. The consent flow uses a double-submit CSRF cookie (_hadron_csrf) — if cookies are blocked, the form POST is rejected with HTTP 403.

What's actually happening¶

For the curious: the OAuth dance follows the MCP OAuth 2.1 specification. The full sequence:

Claude Desktop fetches the Protected Resource Metadata to discover the Authorization Server.
Fetches AS metadata to discover the /oauth/register, /oauth/authorize, and /oauth/token endpoints.
Registers itself via Dynamic Client Registration (RFC 7591) and receives a client_id.
Generates a PKCE code-verifier + challenge (RFC 7636).
Opens a browser to /oauth/authorize with the challenge.
After you sign in + approve, the server redirects back to Claude Desktop with an authorization code.
Claude Desktop exchanges the code (plus the PKCE verifier) at /oauth/token for an access token.
Claude Desktop uses the access token as Authorization: Bearer … on every /mcp request.

The access token is the same shape as a portal-minted API key (hdr_user_<…>), which is why both kinds show up on the same API keys page. See Authentication for the conceptual overview of why Hadron uses a single credential format at the server layer.