Install Hadron in OpenCode¶

OpenCode is a terminal coding agent with built-in MCP support. This guide adds Hadron as a remote MCP server and signs in with OAuth, so the h-* tools (memory search, read/write, specs, chat) are available to OpenCode's agent.

OAuth is the recommended path: OpenCode runs the handshake (PRM → AS metadata → Dynamic Client Registration) and stores a token that auto-refreshes — no plaintext key in your config, and a clear audit row on your portal API-keys page. For the static-token alternative, see below.

What you'll have at the end¶

A hadron MCP server in OpenCode with the h-* tools available in agent mode.
An OAuth token managed in ~/.local/share/opencode/auth.json — no token in your config file.
A row on your portal API-keys page with a source badge like OAuth: dcr_….

What you need¶

OpenCode installed — opencode --version. Install with brew install opencode (see opencode.ai).
A Hadron account at hadronmemory.com.
A model provider configured in OpenCode — it needs an LLM to drive the tools (see Pick a model).

Step 1 — Register the Hadron MCP server¶

Add a hadron entry under mcp in your OpenCode config (~/.config/opencode/opencode.json for all projects, or a project-local opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "hadron": {
      "type": "remote",
      "url": "https://srv.hadronmemory.com/mcp",
      "enabled": true
    }
  }
}

Leaving out a headers block is what makes OpenCode use OAuth — it sees the server's 401 + WWW-Authenticate and starts the flow.

opencode mcp auth hadron

A browser opens to Hadron's sign-in page. Sign in (via GitHub if prompted), review the consent screen (client name, mcp scope, the Hadron resource), and click Approve. OpenCode stores the token and refreshes it automatically.

Run this in your own terminal — the local OAuth callback listener has to stay alive while you sign in.

Step 3 — Verify¶

opencode mcp auth list   # ✓ hadron  authenticated
opencode mcp list        # ✓ hadron  connected

Then, in an OpenCode session, ask "List my Hadron memories." — the agent calls h-list-memories and prints what your account can reach. opencode mcp debug hadron shows the connection/OAuth state if you need to dig in.

Pick a model that can drive the tools¶

OpenCode is model-agnostic, but Hadron's MCP surface is large (~34 tools, URN grammar, scoped read/write). Small local models drive it unreliably — use a strong tool-caller for real work:

Cloud (recommended for tool use) — a strong model such as ollama-cloud/glm-5.1 or ollama-cloud/kimi-k2.7-code, or any Anthropic/OpenAI model you've authed. Set a default with the top-level "model" key, or pick per session with opencode -m <provider>/<model>.
Local (offline / private) — point a provider at a local llama.cpp server on http://localhost:8080/v1. Fine for chat/coding; expect weaker multi-tool reliability.

A config that combines a cloud default with a local option you can switch to:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama-cloud/glm-5.1",
  "provider": {
    "llamacpp": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "llama.cpp (local)",
      "options": { "baseURL": "http://localhost:8080/v1" },
      "models": { "local": {} }
    }
  }
}

opencode -m llamacpp/local then routes to whatever model ~/models/serve.sh has loaded on :8080.

Alternative: static AppKey¶

To use a portal AppKey (or a hdr_user_* personal token) instead of OAuth, put it in a headers block and turn OAuth off:

{
  "mcp": {
    "hadron": {
      "type": "remote",
      "url": "https://srv.hadronmemory.com/mcp",
      "oauth": false,
      "headers": { "Authorization": "Bearer hdr_app_…" },
      "enabled": true
    }
  }
}

Simpler, but it stores a long-lived token in plaintext in your config — prefer OAuth, and never commit the file. Get an AppKey from the portal's Client tab (see Connecting an MCP host).

Local development (a local hadron-server)¶

OpenCode's OAuth requires HTTPS, so OAuth against a local hadron-server (http://localhost:4000) needs a tunnel:

cd hadron-server && pnpm dev                    # listens on :4000
cloudflared tunnel --url http://localhost:4000  # copy the printed https URL

Register a second server (e.g. hadron-local) pointing at the tunnel URL, then opencode mcp auth hadron-local. Or skip the tunnel and use the static-AppKey path straight against http://localhost:4000/mcp — a bearer header needs no HTTPS.

Multi-App users — pin an App¶

If your account belongs to more than one Hadron App, the agent may need to know which one a project uses. Read tools (h-list-memories, h-find-nodes, h-read-node) work without a selection; chat/session tools need an active App. Add an AGENTS.md in your project root — OpenCode loads it as agent instructions:

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

Ask "List my Hadron apps." (→ h-list-apps) to find your App URNs.

Revoking¶

Each OAuth install creates a row on your portal API-keys page with a source badge like OAuth: dcr_…. To disconnect OpenCode: portal → Account → API keys, find the matching OAuth: row, Revoke. To clear the local token too, run opencode mcp logout hadron.

Troubleshooting¶

mcp list shows "needs authentication" — run opencode mcp auth hadron and complete the browser flow.
The browser never opened — opencode mcp auth hadron prints the authorize URL; open it manually.
Tools are listed but the agent won't use them — usually a weak model; switch to a stronger one (Pick a model).
401 Unauthorized after it was working — the token was revoked in the portal; re-run opencode mcp auth hadron.