Install Hadron in Cursor¶

This guide covers the OAuth-based install path for Cursor's MCP support: paste the Hadron MCP URL into Cursor's settings, sign in once via your browser, and Cursor has access to your Hadron memories — with the option to use Cursor's project rules 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 because each issued token is tied to a clear audit-trail row in your portal API-keys page.

What you'll have at the end¶

A hadron MCP server registered in Cursor with the h-* tools available in agent mode.
A row in your portal API-keys page with a source badge reading OAuth: dcr_…<client>.
(Optional, multi-App users) A Cursor rule that auto-pins one Hadron App per project.

What you need¶

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

Production install¶

Open Cursor → Settings → MCP (or the corresponding panel in your Cursor version — recent versions live under Cursor Settings → Features → MCP).
Click + Add new MCP server.
Pick the HTTP transport.
Fill in the fields:
- Name: hadron
- URL: https://srv.hadronmemory.com/mcp
Save. Cursor performs the OAuth discovery handshake (PRM → AS metadata → DCR) and opens a browser window to Hadron's sign-in page.
Sign in via GitHub if you haven't already; review the consent screen — it shows the client name ("Cursor"), the scope (mcp), and the resource (Hadron's MCP endpoint).
Click Approve. Cursor stores the access token.
The hadron server appears in the MCP list with the h-* tools listed.

Test it: open agent mode and ask "List my Hadron memories." Cursor calls h-list-memories and shows the result.

Local development install (`cloudflared` tunnel)¶

Cursor's OAuth client requires HTTPS, so testing against a local hadron-server needs a tunnel.

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 Cursor¶

In Settings → MCP, add a second server using the tunnel URL. Use a distinct name like hadron-local to keep it separate from the production registration.

4. Verify¶

Confirm tools appear under the hadron-local server in agent mode.

Multi-App users — pin an App per project via Cursor Rules¶

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

The Cursor Rule pattern¶

Cursor loads any .cursorrules file (or rules under .cursor/rules/ in recent versions) in the project root as system instructions for agent-mode interactions 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, ask Cursor in agent mode "List my Hadron apps." — Cursor calls h-list-apps and prints the URNs.

After the rule change, the next Cursor agent session in this directory:

Loads the rule at startup.
Calls h-set-active-app with the URN as its first Hadron tool call.
Subsequent tool calls resolve against the pinned App automatically.

Override mid-session by asking "switch to my Acme App" — Cursor calls h-set-active-app again with the new App.

What happens without a rule¶

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

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

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

[no_active_app] No active Hadron App. Call h-list-apps to see
options, then h-set-active-app with the one you want.

Cursor 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. 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 with a source badge like OAuth: dcr_abc123…. The suffix after OAuth: is the client identifier Cursor registered.

To disconnect Cursor:

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 Cursor returns 401 Unauthorized and Cursor will prompt you to re-authenticate.

Troubleshooting¶

Cursor never opens the OAuth browser window¶

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

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

Look for registration_endpoint (must be present — Cursor's DCR flow needs it) and token_endpoint_auth_methods_supported (must include "none").

Cursor's MCP panel doesn't show OAuth as a transport option¶

Some early Cursor versions only supported stdio MCP servers. The OAuth-over-HTTP path needs a recent build (October 2025 or newer). Check Cursor → About for the version.

Cursor Rule pin doesn't apply on the first call¶

Cursor loads rules at session start, but the agent has discretion over when to follow the instruction. If the first Hadron tool call skips h-set-active-app, make the rule more emphatic (capitalize MUST). For a more robust mechanism (server-side App pinning without instruction-following), watch for the directory-aware regime (b) follow-up — it will send the App URN in the MCP initialize handshake directly, removing the LLM-as-parser dependency.