Skip to content

Connecting an MCP host to Hadron

This tutorial walks through connecting any MCP-compatible AI tool to a Hadron app so the tool's LLM can read and write your knowledge graph through Hadron's h-* MCP tools.

It covers seven hosts: Cursor, GitHub Copilot, Claude Desktop, Codex CLI, Cline, Windsurf, and Antigravity. For Claude Code, see the Chatbot end-to-end test (Path B) — that path uses the optional hadron-client proxy and is documented as part of the Claude Code testing flow.

What you'll have at the end

  • A Hadron app of type Workstation linked to an agent
  • An app key wired into your MCP host's config
  • Your host showing hadron as a connected MCP server with h-* tools listed

What you need

  • A Hadron portal account at hadronmemory.com with admin access to an organization
  • One of: Cursor, VS Code with GitHub Copilot, Claude Desktop, Codex CLI, Cline, Windsurf, or Antigravity
  • An existing agent in the org (or follow Building an agent first)

How it works

Most MCP hosts support HTTP MCP servers natively: you give them a URL and a bearer token, and they call the server directly. Hadron serves MCP at https://srv.hadronmemory.com/mcp, and the bearer token is your app key. No local proxy is needed.

┌────────────────┐        HTTP + Bearer        ┌───────────────┐
│  MCP host      │ ──────────────────────────► │ Hadron Server │
│ (Cursor, etc.) │                             │  /mcp         │
└────────────────┘                             └───────────────┘

The Hadron portal generates the right config file shape for each host and bundles them into a setup zip you download from the Client tab.

Part 1 — Set up your app

1.1 — Create or pick an app

  1. In the portal, go to Apps.
  2. Either pick an existing Workstation app or click + New app:
  3. Name: e.g. my-cursor-laptop
  4. Type: Workstation
  5. Role: Contributor (writes) or Reader (read-only)
  6. Organization: the org that owns the agent

On the app detail page → Settings:

  1. Pick the agent you want this host to reach. (Post-008-agent-installation, each App references exactly one Agent — the legacy multi-agent / role choice is gone.)
  2. Confirm mcp is in the agent's surfaces (agent detail → Settings). If only api is listed, add mcp.

Whether the host can write to the agent's knowledge memories is set on the Agent's definition, not the App: each attached memory carries an AgentMemoryItem.role of read or read-write. The agent's own system memory is universally read-only from any App context — edits to the conversation design happen in the Agent ownership surface, not through MCP. See Memory access for the full picture.

1.3 — Pick your MCP host(s)

Still on the app detail page → Client tab:

  1. Tick every host you plan to use — you can pick more than one.
  2. Enter a label for the new app key (e.g. cursor-mar26).
  3. Click Download setup files (.zip).
  4. Save the displayed key somewhere safe — the portal won't show it again.

The zip contains one or more of the following, depending on which hosts you ticked:

Host File in the zip Where it goes
Cursor .cursor/mcp.json Project root
GitHub Copilot .vscode/mcp.json Project root
Codex CLI .codex/mcp.json Project root
Cline .cline/mcp.json Project root
Claude Desktop claude_desktop_config.json Merge into the global config
Windsurf global-configs/windsurf-mcp_config.json Merge into ~/.codeium/windsurf/mcp_config.json
Antigravity global-configs/antigravity-mcp_config.json Merge into ~/.antigravity/mcp_config.json

The zip also contains a README.md with the same install paths.

Part 2 — Install the config in your host

Pick the section for your host. Each one ends with a verification step.

Cursor

  1. Extract .cursor/mcp.json into the root of the project you want Hadron memory in.
  2. Restart Cursor (or Cmd/Ctrl-Shift-P → Reload Window).
  3. Open Cursor's MCP settings (Settings → Features → MCP) and confirm hadron shows a green dot.

The shape of .cursor/mcp.json:

{
  "mcpServers": {
    "hadron": {
      "url": "https://srv.hadronmemory.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_APP_KEY",
        "Content-Type": "application/json"
      }
    }
  }
}

Cursor docs: cursor.com/docs/mcp.

GitHub Copilot (VS Code)

  1. Extract .vscode/mcp.json into the project root.
  2. Reload the VS Code window.
  3. Open the Copilot Chat side panel and pick Agent mode. The hadron server should appear in the tool picker.

Copilot docs: code.visualstudio.com/docs/copilot/chat/mcp-servers.

Claude Desktop

Claude Desktop reads a single global config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Open that file and merge the mcpServers.hadron block from the zip's claude_desktop_config.json into it (don't overwrite — you may already have other MCP servers there).

Restart Claude Desktop. The hammer icon in the chat input should show the Hadron tools.

Codex CLI

  1. Extract .codex/mcp.json into the project root where you'll run codex.
  2. Run codex in that directory; it picks up the config automatically.

Cline

  1. Extract .cline/mcp.json into the project root.
  2. Reload your editor. Cline lists Hadron under its MCP servers panel.

Windsurf

Windsurf uses a global config at ~/.codeium/windsurf/mcp_config.json.

Merge the mcpServers.hadron block from global-configs/windsurf-mcp_config.json (in the zip) into that file. Restart Windsurf.

Antigravity

Antigravity uses a global config at ~/.antigravity/mcp_config.json.

Merge the mcpServers.hadron block from global-configs/antigravity-mcp_config.json (in the zip) into that file. Restart Antigravity.

Part 3 — Verify the connection

Open a chat in your host and ask:

List my Hadron memories using the h-list-memories tool.

You should get back the list of memories the linked agent can reach. If the list is empty, the app has no agent linked yet — go back to Step 1.2.

For a richer smoke test:

Use h-find-node to search for any node containing the word "welcome", then h-read-node on the first result.

If the agent has at least one knowledge memory attached with AgentMemoryItem.role = read-write, also try:

Create a test node at loc: "scratch/hello" with content "Hello from ".

Check the node appeared in the portal under the agent's writable memory.

Troubleshooting

Host doesn't list hadron as a server
The config file is in the wrong place, or the host needs a restart. Check the path against the table in Step 1.3 and reload the window.
401 Unauthorized or "auth failure" in the MCP logs
The app key is wrong, or the key has been revoked. Generate a new key from the Client tab, replace it in the config, and restart the host.
hadron connects but h-list-memories returns nothing
The app has no agent linked yet, or the linked agent has no memories. Go to the app's Settings tab and confirm both.
**hadron is connected but tools error with "agent has no mcp
surface"**
The agent's surfaces array doesn't include mcp. Open the agent detail page → Settings and add mcp.
**Multiple projects share one host (e.g. Cursor) — which app key
wins?**
Project-scoped configs (.cursor/mcp.json, .vscode/mcp.json, .codex/mcp.json, .cline/mcp.json) are per-project — each project uses its own app key. Global configs (Claude Desktop, Windsurf, Antigravity) use a single shared app key for the whole host.

What's next

  • Chatbot end-to-end test (Path B) — if you want hooks and guided sessions with Claude Code, set up the hadron-client proxy and follow the Claude Code path.
  • Building an agent — create a new agent and memories to connect to.
  • Architecture — understand how apps, app keys, and AgentMemoryItem roles cap what the host can do.