Skip to content

MCP tools

Hadron exposes around thirty h-* tools through the Model Context Protocol. Any MCP host (Claude Code, Cursor, the Claude desktop app, …) connected to a Hadron MCP server can call them to read and write memory, drive chats, and run actions.

This page is a categorized lookup of the tool surface — name, purpose, required inputs, and what the call returns. For walk-throughs that use these tools end-to-end, see Connecting an MCP host and Adding nodes to a memory.

Connecting

The MCP server is shipped as part of hadron-server and registered in your MCP host's config (.mcp.json, Claude Desktop's settings, etc.). The fastest way to wire it up in a coding-agent project is the install script, which configures .mcp.json and the Spec Kit extension in one step.

Once connected, every tool below is callable as mcp__hadron__<tool-name> (or under whatever namespace your host uses).

Active memory

Most tree tools take an optional memoryUrn (or a loc that starts with one). When you don't pass one, they fall back to the active memory for the session. Bind it once with h-set-active-memory and subsequent calls operate on that memory by default. This is the recommended pattern — passing memoryUrn on every call is verbose and error-prone.

If your search returns "No nodes found" repeatedly across queries that should match, treat it as a configuration smell — verify the active memory is bound to the memory you expect rather than assuming the topic isn't covered.

Memory selection

Tool Purpose Key inputs
h-list-memories List every memory accessible to the caller, with URN and access level (read-only or read-write). (none)
h-set-active-memory Bind a memory as the session default for subsequent calls. memoryUrn
h-sync-graph Trigger a one-shot GitHub source sync for a memory backed by a Git source. memoryUrn

The list returned by h-list-memories is the authoritative inventory of where you can read and write — agents are not memories, and apps are not memories. If a memory you expect isn't in the list, your identity is missing access to it.

Sessions

Sessions are optional but strongly recommended for traceability. Every node created inside a session is attributed to it; ending the session records summary metrics.

Tool Purpose Key inputs
h-start-session Open a work session and get a session ID for attribution. description (required); optional type (DEVELOPER/CHATBOT/AUTOMATION/EDGE), repo, branch, prNumber, language, llmModel, parentSessionId, prevSessionId
h-end-session Close a session. Records summary and final token / error counts. id (required); optional summary, errorCount, turnCount, inputTokens, outputTokens

Returns: h-start-session returns a session ID and a 6-phase protocol hint. The protocol's middle phases ("save plan", "update memory") are bookkeeping markers under Spec Kit — plan.md is the saved plan; memory updates flow through h-add-node / h-update-node directly. Always close with h-end-session.

Browse nodes

Read-only node lookups. None of these mutate anything.

Tool Purpose Key inputs
h-find-nodes Search nodes by name, tags, or description. query (required); optional parentRel, memoryUrn, brief, limit
h-read-node Read a single node by loc path or full URN. loc
h-read-next-node Read the next sibling under a parent, ordered by seq. Used to walk a conversation flow stage by stage. parent; optional current
h-list-nodes Browse the tree under a parent — names + descriptions only, optionally to a depth. optional parentRel, memoryUrn, depth

h-find-nodes takes a brief: true flag that returns name, URN, description, and edges only — useful for triage before deciding which nodes to read in full. h-read-node returns the full content including frontmatter, edges, properties, and data.

Mutate nodes

All require write access to the target memory.

Tool Purpose Key inputs
h-add-node Create or upsert a node. The node type defaults to info; pass parent (a parent-type container) for sections. loc, name; optional nodeType, description, content, seq, tags, properties, data, edges, memoryId, llmModel, aiAgent
h-add-parent-node Create a section/category container node. Convenience wrapper that pins nodeType: parent. loc, name; optional description, seq, tags
h-update-node Partially update an existing node — only the fields you pass change. loc; any subset of name, nodeType, description, content, seq, tags, properties, data, edges, llmModel, aiAgent, plus reason (stored in version history)
h-add-edge Add a single outgoing edge from one node to another. Non-destructive (other edges on the source are preserved), idempotent on the (source, target, label) triple. Cross-memory edges allowed if the caller can read the target memory. sourceUrn (fully-qualified node URN), targetUrn (URN or ID), label
h-move-node Move a node (and optionally its subtree) within a memory or across memories. from, to; optional targetMemoryUrn
h-delete-node Delete a node. Soft-delete by default (sets deletedAt); pass hard: true for a row delete. Refuses with descendants unless recursive: true. Hard-delete refuses cross-memory edges unless cascadeCrossMemoryEdges: true. urn (fully-qualified); optional hard, recursive, cascadeCrossMemoryEdges

edges on h-add-node / h-update-node is an array of { targetId, label } — passing one replaces the source node's full edge set. Use h-add-edge when you want to append a single edge without touching the rest. Targets can be loc paths or full URNs. Adding an edge to a missing target does not fail at write time; h-validate will flag it later.

Validate & run

Tool Purpose Key inputs
h-validate Walk the active memory and report broken edges, missing content, and structural issues. (none)
h-run-action Load an action-type node, resolve its dependencies, and execute it. loc; optional args (key-value object)

h-validate is safe to run any time — it's a read-only sweep. h-run-action is what makes action nodes executable from any MCP host: write the action once, run it from Claude Code or any other host the same way.

Chat

The chat tools drive a Hadron-managed chatbot session — what the Chat API reference documents from the GraphQL side. The MCP tools are equivalent: they call the same resolvers, return the same shapes.

Lifecycle

Tool Purpose Key inputs
h-chat-start Start a chat with an agent. Returns the system message, tool schema, and initial stage. agentId; optional userId, conversationName
h-chat-send Save a user message and return the recompiled system message + history for the next LLM turn. chatId, userMessage
h-chat-process Save the LLM's respond({ message, data, next_stage }) tool call. Extracts data, evaluates routing edges, returns the display message and any transition. chatId, message; optional data, next_stage

Routing & navigation

Tool Purpose Key inputs
h-chat-get-routing-map Download the agent's full conversation graph (topics, conversations, stages, edges). agentId
h-chat-get-route-history Read the route history and goal stack for an existing chat. chatId
h-chat-push-goal Push a new goal onto the chat's goal stack — typically when the LLM detects an implicit detour. chatId, description; optional createdBy (ASSISTANT default, or USER)
h-chat-pop-goal Mark the current top goal complete and return to the previous one. chatId

Training & personas

Tool Purpose Key inputs
h-chat-add-training-entry Record a user statement and the conversation it should route to — grows goalSignals over time. agentId, userStatement, matchedConversation; optional language
h-chat-define-persona Define a test persona for automated chat testing. agentId, name, description, openingMessage; optional conversationName, followUpMessages, expectedConversations
h-chat-list-personas List the personas defined for an agent. agentId
h-chat-run-persona Drive a chat with a persona one step at a time. Returns the chat ID and current step index. agentId, personaLoc; optional step, chatId

For the broader picture — what topics, conversations, stages, and edges are — see Conversation routing.

App selection

For OAuth callers who can see more than one Hadron App, two tools pin an App as the active scope for the rest of the MCP session:

Tool Purpose Key inputs
h-list-apps List the Hadron Apps the caller has access to, each with its canonical URN and the caller's role on it. (none)
h-set-active-app Pin an App as the active scope. Subsequent App-scoped calls (h-list-memories, h-find-nodes, etc.) resolve to this App until the session ends. app (canonical App URN or unique display name)

See MCP App selection for the full walk-through — typed-error vocabulary (app_identifier_ambiguous, app_not_found, …), short-form resolution rules, and the session-lifecycle behavior.

Server identity

Tool Purpose Key inputs
h-server-info Return the deployment URL and version of the hadron-server this MCP session is bound to. Useful when a caller has multiple MCP namespaces wired up and needs to know which one a tool call landed on. (none)

Does not require an active App or any memory access — safe to call before authentication is established.

Stability and changes

The MCP tool surface is stable — the names and core signatures have not churned. Recent activity adds capabilities (personas, goal stack tools) and fixes edge-case bugs. New tools are additive; removals would be breaking and have not occurred.

If a tool you call returns an unexpected error, check hadron-server's release notes before assuming a regression.