Skip to content

MCP tools

Hadron exposes about seventy hadron_* tools through the Model Context Protocol. The exact set a connection sees depends on who is connected (a signed-in user, an App key or an impersonated session see slightly different sets) and on the server version, so treat your host's own tool list as the live inventory. Any MCP host (Claude Code, Cursor, the Claude desktop app, …) connected to a Hadron MCP server can call them to read and write memory, run actions and keep comments. The agent team is not on this surface. Its workers, chat, tasks, tickers and wakes are driven from the CLI and the portal; the former MCP tools for them are listed, with where each one went, under Former agent-team MCP tools.

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.

Paging

Not every list tool pages. Those that take limit/offset or first/after (the rows below name them) page: when you leave the size out, the server returns 20 rows or fewer, and each has its own cap. Asking above the cap returns a page of the cap, not a refusal. A cap is a maximum, not a default, so the "default 20, cap 200" in the rows below are two different numbers. To read a whole list from one of these, keep asking for the next page until the response says no more rows exist (an empty page, or you have reached total); do not stop at the first short page.

Some list tools return everything in one response and take no paging arguments, for example hadron_list_memories. Making every list page is a rule the platform is still building, so check a tool's row for limit or first before you loop on it.

The 20-row defaults are what hadron-server main serves (PR #2364, merge 7f973f35); a deployment that predates that merge still answers with its older default, so pass an explicit size if you depend on one.

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).

X-Hadron-Client-Id — keeping your selections across reconnects

MCP clients re-initialize transparently: a server restart replaces the session without telling the agent driving it. Everything held per-session goes with it — the active App, the active memory, the active scope and the active organization. The symptom is calls that work for a while and then start refusing, or searching somewhere else, for no visible reason.

A client that sends a stable instance id gets all four restored on the next connection:

X-Hadron-Client-Id: <stable opaque id>

What an integrator needs to know:

  • Stable across restarts. A per-process id defeats the purpose — it is a new client every time.
  • Per client instance, not per user. Two clients on one account keep separate selections, so changing App in one does not silently change it in the other. Sharing an id across instances works and is a deliberate choice, not the default.
  • Opaque, trimmed, and max 200 characters. Empty or over-length is treated as not sent rather than truncated — truncating would collide two instances onto one selection.
  • Entirely optional. Send nothing and you get exactly the previous behaviour: selections live for the connection and no further.
  • Restoration is re-authorized every time, so a restored selection can never hand back access the user has since lost. It also needs a user identity — a pure App-key caller has no per-user selection to restore.

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 hadron_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.

Search is the exception. hadron_find_nodes never falls back to the active memory: with no memory selector it runs under the search ladder — the active scope, the active App, the active organization, or failing those your own user-owned memories. If a search returns "No nodes found" across queries that should match, read the scope line at the top of the result before assuming the topic isn't covered: it names what was actually searched.

Memory selection

Tool Purpose Key inputs
hadron_list_memories List every memory accessible to the caller, with URN and access level (read-only or read-write). (none)
hadron_set_active_memory Bind a memory as the session default for subsequent calls. memoryUrn
hadron_create_memory Create a memory. memoryClass is knowledge (default), group, personal or private. It does not select the new memory: the result gives its URN, class and id, and you pass the URN to hadron_set_active_memory. See Creating a memory for who may create which class. name (required); optional memoryClass, org, shortDescription, description, tags, visibility
hadron_create_app_memory Create a NEW app-class memory in an App (organization-owned or user-owned) that has an Agent installed. On an organization's App the caller must be an ADMIN or OWNER of the App's organization (or a platform ADMIN or OWNER); on a user-owned App, its owner. Always as themselves, outside a worker session; App keys, runs and impersonation are refused. It does not attach an existing memory, and it does not select the new memory. See Creating an App memory. app, name (both required); optional shortDescription, description, tags
hadron_sync_graph Trigger a one-shot GitHub source sync for a memory backed by a Git source. memoryUrn
hadron_unlock_memory Unlock an encrypted PRIVATE memory for THIS MCP session. Supply exactly one of passphrase or dataKey; owner only. While unlocked, reads return plaintext and writes are encrypted; other sessions are unaffected. The key lives only in server memory and is dropped when the session closes, on hadron_lock_memory, or after the memory goes unused for the key-cache idle window (24 hours by default; every read or write refreshes it). After a long quiet stretch a read may report the memory locked again: call this again. memoryUrn; one of passphrase, dataKey
hadron_lock_memory Drop this session's key for an encrypted memory: reads return to locked markers and writes to it are rejected. Other sessions that hold the key are unaffected. memoryUrn

The list returned by hadron_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.

Creating a memory

hadron_create_memory calls the same createMemory rules as the GraphQL mutation, so the tool can never do what the API refuses.

Class What it needs Who owns it
knowledge (default) org, and the organization's memory.create permission. The organization.
group org, and the organization's memory.create permission. The creator becomes the group's first owner.
personal, private Owner-only. Omit org to create one in your own namespace; pass org to create it in an organization you are a live member of. You.

Inputs:

  • name — required, non-empty. Its slug becomes the tail of the memory's URN (My Notes becomes my-notes).
  • memoryClass — knowledge (default), group, personal or private.
  • org — organization URN or id. Required for knowledge and group.
  • shortDescription, description, tags — optional descriptive fields.
  • visibility — PUBLIC, ORGANIZATION or GROUP. A knowledge memory takes PUBLIC or ORGANIZATION (default ORGANIZATION); a group memory is always GROUP; personal and private take none.

What it does not do:

  • It takes no owner, App or agent argument and does not attach the memory to an App.
  • It does not create system or App memories. To add a memory to an App, use hadron_create_app_memory.
  • It does not select the new memory. Pass the returned URN to hadron_set_active_memory.
  • An App-key caller has no user to own a personal or private memory, so it is refused there exactly as it is over GraphQL.

Available from hadron-server 2646f28a (hadron-server#2550). Check hadron_server_info against your deployment before relying on it.

Creating an App memory

hadron_create_app_memory calls the same createAppMemory rules as the GraphQL mutation, so the tool can never do what the API refuses. It adds a new app-class memory to an App, organization-owned or user-owned, that has at least one Agent installed. The App's participants read and write it; the Agent's owning organization gains no access. For who may do it and why, see Adding a memory of its own to an App.

Inputs:

  • app — required: the App's id, URN or prefixed URN.
  • name — required, non-empty. Its slug becomes the tail of the memory's URN.
  • shortDescription, description, tags — optional descriptive fields.

It takes no existing-memory id and no Agent selector. On success it returns the new memory's URN, class (app) and id, and does not select it: pass the URN to hadron_set_active_memory.

Refusals: FORBIDDEN (on an organization's App, neither an ADMIN or OWNER of the App's organization nor a platform ADMIN or OWNER; on a user-owned App, not its owner; or a refused principal), AGENT_NOT_INSTALLED and BAD_USER_INPUT (empty name). A worker session is refused even when the person driving it could do the same thing outside the session.

Available from hadron-server a87ba3517 (hadron-server#2670, for hadron-server#2661), for organization-owned Apps. A user-owned App's owner is admitted from hadron-server ac44386e (hadron-server#2848, for hadron-server#2843); before that revision a user-owned App was refused. Check hadron_server_info against your deployment before relying on it.

Sessions

\"Session\" means the Hadron session, not your chat session

Throughout this page, a session is the Hadron Session row — the thing hadron_start_session opens and hadron_end_session closes. Your chat session (the Claude Desktop window, the Claude Code conversation) is a separate lifecycle, and closing it does not end the Hadron session: only hadron_end_session does that. Nothing ends a session because it went quiet: a quiet session stops reading as live, and it stays open until it is ended (cor:agt:020:11). See the two kinds of session.

A session is optional but recommended for traceability. Every node created inside one is attributed to it; ending it records summary metrics.

MCP starts plain sessions, never worker sessions (cor:agt:020:03; hadron-server#3208, deployed at 99246d46). A worker session is a named teammate's stint, and it is created and resumed through the CLI (hadron team session start --as <worker> --tool <tool>). It works in two halves:

  • MCP cannot create or resume one. hadron_start_session refuses a workerRef or a launchGrant with MCP_WORKER_BINDING_UNSUPPORTED before it reads or writes anything, so the answer is the same whether the worker exists or not and no session, hold or grant is touched. A plain session you start here is not a worker session.
  • A worker session the CLI created still attributes core MCP calls. Name it in the session argument of a write, or send its id in the X-Hadron-Session header, and the node or comment is attributed to it (hadron-server#1081).
Tool Purpose Key inputs
hadron_start_session Open a plain session and get a session ID for attribution. A workerRef or launchGrant is refused MCP_WORKER_BINDING_UNSUPPORTED; start a worker session with the CLI. description (required); optional type (DEVELOPER/CHATBOT/AUTOMATION/EDGE), repo, branch, prNumber, customerId, language, llmModel, family, parentSessionId, prevSessionId
hadron_end_session Close a session, and for a worker-bound one write its closing handoff — the record the next stint inherits at bind (hadron-server#1029). Closing your chat session does not do this. The receipt states the end reason (ended for an explicit close; for a session that had already ended, the original time and reason stand). id (required); optional handoff (the thing the next driver reads, worker-bound sessions only; a failed write refuses the end, so retrying is safe), summary (a display-only label the successor never sees), resumeClaim (true also writes a resume claim for the CLI to redeem, hadron team session start with no worker named; your own worker session only), errorCount, turnCount, inputTokens, outputTokens
hadron_whoami Answer "what am I driving right now?" — your own open sessions, each with its App, when it started and the worker it is bound to, if any. A plain session reads "working as: nobody". A bound row is a worker session the CLI started. Every successful answer opens with an active memory: line naming the memory selected on this connection — active memory: <urn> (<name>), with the name only when the memory has one — or active memory: none when no memory is selected or the selected one is deleted or no longer readable by you. The line describes the connection, not any session row, and is not a guarantee of where a write lands. Optional app, workerRef (both narrow the set before paging), limit (default 10, cap 50), includeEnded (also list recently ended sessions, each with its end time and end reason: ended, superseded, expired, or unknown for a legacy row)

Returns: hadron_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 hadron_create_node / hadron_update_node directly. Always close with hadron_end_session.

hadron_start_session is strict: it needs App context and fails with [no_active_app] without it. See MCP App selection.

Attribution and the end gate

hadron_start_session stamps the caller's user id on the session. For an OAuth or PAT caller that is you; for a pure App-key caller it is null. That stamp is what makes the session yours — it drives the attributed-user self-read, and it decides who may close the session.

hadron_end_session is gated. Exactly two principals may end a session through MCP:

  • a pure App-key principal, for its own App's sessions, or
  • the authenticated user the session is attributed to.

Anyone else gets Forbidden: session "<id>" belongs to a different App or user. The App branch requires the absence of a user id: when you call as a user with an active App selected, the selection is a scope, not a credential — so co-members of one App cannot end each other's sessions. (The GraphQL endSession applies the same gate, plus a platform-admin branch that MCP does not expose.)

Ending a session you didn't start is therefore refused rather than silently succeeding. The full read/write table is in the Authorization reference.

Worker binding is not on this surface; neither is the rest of coding provenance

hadron_start_session starts a plain session only (see above). The coding-session fields — transcriptPath, host, agentRef — are set through GraphQL startSession and the hadron team session CLI commands. There is no MCP equivalent of updateSession either; hadron_end_session is the only session write MCP offers.

Recovering after a context compaction

A worker session lives in the CLI's binding for the worktree, not in your MCP context. After a compaction, recover it with the CLI (hadron team session whoami --check), as walked through in Recover after a context compaction. hadron_whoami here lists your open sessions and the worker each is bound to, which is how you read back a session id.

Browse nodes

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

Tool Purpose Key inputs
hadron_find_nodes Relevance-ranked node search. mode: keyword (default, stemmed full-text), vector/hybrid (semantic, needs the memory's vector index), or regex. Also filters structurally by objectType and a where predicate. query (required — use "*" or "" for survey/list-all mode); optional mode, scope (see Search scopes), parentRel, childrenOf, memoryUrn, memoryUrns, allMemories, objectType, where, isRunnable, nodeKind (see Comments), nodeType, nodeTypes (see Default node-type exclusion), brief, limit, minScore, expand, granularity
hadron_search Find a known entity by id, URN or name across kinds — organizations, memories, nodes, agents, apps, AI service configs, users — in one ranked list. Matching is case-insensitive substring — except pk, which is exact — and never stemmed; for concept search over node text use hadron_find_nodes. query (required); optional entityTypes, fields (urn, name, description, pk, or content — node bodies, opt-in, skips encrypted memories), scope (applies to the memory and node slices), limit
hadron_get_node Read a single node by loc path or full URN. loc
hadron_get_nodes Batch read: the full per-node projection (meta, edges and a contentScope body, identical to hadron_get_node) for many nodes in one call. Two mutually exclusive forms: refs, an explicit list of node primary keys or fully-qualified URNs, returned in input order; or memoryUrn plus locPrefix, every readable node whose loc starts with the prefix in one memory, returned in loc order. Unreadable and non-existent refs are reported in a separate unavailable list and never fail the batch; a ref of the wrong shape (relative, unqualified, or another entity kind) is a loud error. Exceeding the node-count cap is an error; exceeding the response-size cap returns a partial result flagged truncated. raw returns include tags as written instead of resolving them. refs, or memoryUrn + locPrefix; optional contentScope (content by default, abstract or all), raw
hadron_get_next_node Read the next sibling under a parent, ordered by seq. Used to walk a conversation flow stage by stage. parent; optional current
hadron_list_nodes Browse the tree under a parent — names + descriptions only, optionally to a depth. optional parentRel, memoryUrn, depth

hadron_find_nodes takes childrenOf to list only the direct children of a loc: a node whose loc is exactly that loc plus one more segment, with no further colon. "" means the top-level nodes. It reads loc strings only, not edges and not parentRel, so a child whose parent has no node of its own is still listed. It applies in every mode, with the same access checks and default node-type exclusion as the rest of the search, and pairs with memoryUrn because a loc is per memory. With no query and no sort the order is the sibling order: positioned nodes first, then by loc. Unlike parentRel, which scopes the whole subtree, it returns one level. The same filter is NodeFilter.childrenOf on GraphQL findNodes.

Default node-type exclusion

An unqualified hadron_find_nodes leaves out system and chat-message nodes in every mode: keyword, regex, vector, hybrid and the no-query list. childrenOf adds and removes no default exclusion, so listing the children of a team chat's messages loc does not return its chat-message nodes unless you name the type. Only those two types are excluded: an adopted Channel can keep legacy message children, and those are still returned.

Naming a type wins. nodeType: "chat-message" (or "system"), or a nodeTypes list, replaces the default and returns those nodes, with the same access checks. Naming system lifts only this node-type default, not the separate memory-class SYSTEM default: a system-class memory still needs memoryClasses, or the memory named in memoryIds.

record nodes stay searchable, so the messages of a chatbot chat root, which are record, are still returned. To read a chat, use hadron team chat read or hadron chat read rather than search.

GraphQL findNodes follows the same rule through NodeFilter.nodeType and NodeFilter.nodeTypes. The rule is cor:api:090:02.

hadron_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. hadron_get_node returns the full content including frontmatter, edges, properties, and data.

On a memory with a structured schema, narrow to a collection with objectType and filter by exact field values with the where predicate — where composes with every mode (it filters, then the mode ranks the survivors). Ordering by a property (sortProperty) is not exposed on this tool — use GraphQL findNodes or the CLI's --sort-property to sort by a property; from MCP, sort client-side. See Query nodes by their properties.

Agent definitions

What an Agent knows how to do, read across its base chain, and the two settings that shape it. Each tool takes the Agent's id or URN as agentRef and does exactly what its GraphQL twin does, with the same gate and refusals.

Tool Purpose Key inputs
hadron_agent_set_base Set, change or clear the one base Agent this Agent extends. Only whoever manages the Agent may. Answers with the Agent and Base: <URN> or Base: none. GraphQL setAgentBase. agentRef, baseRef (required; null clears, so leaving it out never clears by accident)
hadron_agent_set_index_refs Set or clear the tasks-index and processes-index pointers. Omit a pointer to keep it, null clears it. Only whoever manages the Agent may. GraphQL setAgentIndexRefs. agentRef; optional tasksIndexRef, processesIndexRef
hadron_agent_tasks The Agent's tasks: every runnable node in its effective system memory, and every task a tasks index in the chain lists, each once. GraphQL agentTaskList. agentRef
hadron_agent_processes The Agent's processes: the ones a processes index in the chain lists (it starts or owns them), then the ones with a stage edge, named stage …, to one of its tasks (it's involved), each once. GraphQL agentProcessList. agentRef
hadron_agent_boot_prompt Read the compiled boot prompt a chat or run with this Agent (in this App, when you give appRef) would be served now, with its platform variables filled as a chat fills them. For an MCP-only agent reading its own prompt. A pure read: it binds no worker, starts no session and records nothing. GraphQL agentServedBootPrompt. agentRef; optional appRef, llmModel

Each entry is a - <name> — <URN> line, followed by whichever of these apply:

  • Kind: starts or owns or Kind: involved: processes only.
  • Trigger: <edge name>: the name of the index edge that lists it. Where two indexes in the chain list one task, the nearest Agent's wins. A task no index lists, and every involved process, has none.
  • Inherited from: <agent URN> and Read through: <node URN>: the entry comes from a base. It keeps the base's URN; Read through is the same loc in this Agent's own system memory, where a reader of the Agent can read it.

An Agent with nothing on a list answers No tasks for Agent <ref>. or No processes for Agent <ref>.. Both lists are readable by whoever may read the Agent's system memory; anyone else gets AGENT_NOT_FOUND. An entry outside the chain's memories is listed only when its own memory is readable too.

Inherited nodes on node reads. hadron_get_node, hadron_get_nodes, hadron_list_nodes and hadron_find_nodes read an Agent's system memory through its chain. A node that comes from a base keeps its base URN and carries this line after its revision:

Inherited from: hrn:agent:acme.com:engineer (a base of the Agent read; its edges and records are not shown)

Its edges come back resolved through the Agent that was read, never the base's own. Reading the node directly by its base URN needs access to the base.

hadron_agent_set_base is refused, changing nothing, in this order: for the Agent, AGENT_NOT_FOUND (absent, retired, or one you can't read, so an Agent you can't read is never confirmed to exist) then FORBIDDEN (you can read it but don't manage it); for the base, AGENT_NOT_FOUND (absent, retired, or one you hold no licence to and may not see); then AGENT_ORG_GRANT_REQUIRED, AGENT_ORG_GRANT_INACTIVE or AGENT_SUBSCRIPTION_REQUIRED; then AGENT_BASE_CYCLE and AGENT_BASE_CHAIN_TOO_LONG (at most 4 Agents in a chain). hadron_agent_set_index_refs is refused with the same two for the Agent, then NODE_NOT_FOUND for an index node that doesn't exist or you can't read. It answers with Tasks index: and Processes index: lines, each a URN or none. Refusals read [<CODE>] <message>. See Build Agents on a shared base.

Reading a boot prompt. hadron_agent_boot_prompt answers with three header lines, a blank line, then the prompt text exactly as agentServedBootPrompt returns it. The URNs and numbers below are illustrative:

Served boot prompt for Agent hrn:agent:acme.com:engineer in App hrn:app:acme.com:eng-team: AGENT pointer, revision 7.
Compiled node: hrn:node:acme.com:engineer-system:boot:compiled
Rendered as a chat or run would be given it: no worker, no derived blocks; session.llmModel = claude-sonnet-5-5.

<the prompt text>

Line 1 names the Agent (and the App, when you gave appRef), the pointer level that was served (APP_AGENT or AGENT: this read binds no worker, so WORKER, which the shared enum also has, never appears) and the revision. Line 2 is the compiled node: its URN, or its bare id when its memory isn't readable to you. Line 3 restates how the text was rendered, with the llmModel you passed (empty if you omitted it). The platform variables are filled the way a chat fills them when no worker is bound, so they carry the Agent's values, not a worker's: worker.name is the Agent's name, worker.role its persona role, reports-to, signature and trailer are empty, and session.llmModel is the llmModel you pass. llmModel is at most 256 characters; anything malformed is refused as BAD_USER_INPUT. No derived blocks are appended, and nothing is bound or recorded. The answer is what would be served now, not what your session was given, so an approval between two calls can change it. These read rules describe current behaviour; the specs record them as Proposed, as built (cor:agt:040:10).

  • Without appRef, you get the Agent's own prompt, if you may read the Agent's system memory. This is what the Agent's own pointer alone would serve. It says nothing about an App or a worker that overrides it: an App's install, or a customized worker, may be served a different prompt. An agent running inside an App must not take this text as its own.
  • With appRef, you get what a chat in that App would be given (the install's prompt, then the Agent's). You must be a participant of that App, or hold the App's own key for that App only. The Agent must be installed in the App, and you must be allowed to chat with it. A headless run is never admitted, even one acting for a person.

Anyone who fails any of these checks gets AGENT_NOT_FOUND, the answer for an Agent that doesn't exist: so does asking for a missing App, an App without the install, a retired Agent, or an install whose licence has lapsed. Past that gate come the serve's own refusals, BOOT_PROMPT_NOT_SET, BOOT_PROMPT_TARGET_DELETED, BOOT_PROMPT_NOT_APPROVED and BOOT_PROMPT_NOT_SIGNED, with the same [<CODE>] <message> form. What each one means, and how pointers choose the prompt, is on Serving a boot prompt.

Search scopes

A scope — a "lens" — is a named, ordered list of memories owned by exactly one organization, Agent, or App. It narrows what a search looks at and never grants: a scope's results are its memories ∩ what you may read, and memories you cannot read are reported as a count, never by name. Names are 1–64 characters of [a-z0-9_-], unique per owner; app and global are reserved for the built-in views below.

Tool Purpose Key inputs
hadron_list_scopes List the scopes you may read. With no filter, lists the active App's context — its own scopes, its installed Agents', and its organization's: what a bare scope name resolves against there. optional app, ownerType + ownerRef (one owner's scopes instead), name, limit, offset
hadron_create_scope Create a scope. With no owner ref, the active App owns it. Every memory must be one you can read. name, memoryUrns (ordered, at least one); optional one of organizationRef / agentRef / appRef, description
hadron_update_scope Rename, re-describe, or replace the memory list — memoryUrns replaces, never merges. scope (id); optional name, description, memoryUrns
hadron_delete_scope Soft-delete a scope; its name is free again at once. Attaches or detaches nothing. scope (id)
hadron_scope_explain What a scope resolves to for you: readable memories in order, how many were dropped for access, which owner tier won, the scopes it shadowed, and — with loc — which memory would win for that address. scope (id) or name; optional app, loc
hadron_set_active_scope Set the scope hadron_find_nodes and hadron_search run under when a call names no scope and no memory — or drop it with clear: true. Persisted per client instance, like the active App. scope (id or name), or clear: true

Creating or changing a scope needs CONTRIBUTOR or above on an owning organization, or — for an App or Agent owner — ADMIN of its organization, or ownership of a user-owned one.

A name resolves in an App's context: App › Agent › organization, never unioned. Two installed Agents that each own the name make it ambiguous; pass the id instead.

Which memories a search covers when you don't list them. A search runs under the first of these that applies:

  1. a scope named in the call;
  2. the active scope (hadron_set_active_scope);
  3. the active App — app, its attached memories;
  4. the active organization — global, see Organization selection;
  5. your own user-owned memories.

The active memory (hadron_set_active_memory) is not a rung: search never falls back to it.

Every result says which scope it ran under. An explicit memoryUrn, memoryUrns, allMemories or parentRel on hadron_find_nodes outranks the ambient rungs (2–5), but still intersects with a scope named in the same call. So on MCP, omitting every memory selector does not search everything you can read once an App is active: it searches that App's attached memories. Pass allMemories: true for the everything-you-can-read probe. (The GraphQL findNodes and the CLI's hadron search apply no ambient ladder: with no scope they search your accessible set.) hadron_list_nodes takes no scope: it browses one memory's tree.

Mutate nodes

All require write access to the target memory.

Tool Purpose Key inputs
hadron_create_node Create or upsert a node. The node type defaults to info; pass parent (a parent-type container) for sections. loc, name; optional nodeType, objectType, description, content, seq, tags, properties, data, edges, memoryId, llmModel, aiAgent
hadron_create_parent_node Create a section/category container node: a lightweight node that organizes other nodes. It is stored as an ordinary info node, not a parent-type node; for a parent-type container use hadron_create_node with nodeType: parent. If a node already exists at that URN it is overwritten, not merged: name (omitted: the last segment of the URN), description (omitted: cleared), the content (set to the description when one is passed, otherwise Section: <name>) and tags (omitted: emptied) are all replaced, and the node becomes info. Fields this tool has no input for, such as seq and data, are left as they are, and so are edges created directly (for example with hadron_create_edge), incoming or outgoing. The one exception is this node's outgoing INCLUDE edges that were derived from include tags in its content: they are re-synced to the new content, so an edge whose include tag is no longer in the new content is dropped and a tag newly in it gets an edge. A tag in the description or in the name counts, since either can end up in the content. Refused for governed nodes (comments, boot prompts, reviews, runnable tasks). urn (fully-qualified node URN; a bare ID is refused); optional name, description, tags
hadron_update_node Partially update an existing node — only the fields you pass change. The data argument replaces the whole data bag; use hadron_update_node_data to merge instead. loc; any subset of name, nodeType, objectType, description, content, seq, tags, properties, data, edges, llmModel, aiAgent, plus reason (stored in revision history)
hadron_update_node_data Merge a JSON object into a node's data bag, preserving keys you don't mention. The patch's top-level keys overwrite existing ones; other keys stay; a node with no data takes the patch as-is. Shallow — a nested object value is replaced wholesale, not deep-merged. Patch must be an object (arrays, scalars, and null are rejected). nodeUrn (URN or ID), data (the object to merge)
hadron_create_edge Add a single outgoing edge from one node to another. Non-destructive (other edges on the source are preserved), idempotent on the edge loc. Cross-memory edges allowed if the caller can read the target memory. sourceUrn (fully-qualified node URN), targetUrn (URN or ID); optional name, loc, description, isRunnable
hadron_move_node Move a node with its whole subtree, within a memory or across memories. The node keeps its stable id, so every edge reference stays valid, and it keeps its name — a move changes the address, not the display title. urn (current), targetUrn (destination; a different memory in the target URN performs a cross-memory move); optional overwrite, renameToLeaf (default false — pass true to also overwrite name with the target loc's last atom)
hadron_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
hadron_update_edge Change ONE existing edge's metadata in place: its name, loc, description, runnability, routing priority, routing condition or data. Other edges on the source node are untouched; only the fields you pass change, and null clears a nullable one. It cannot move an edge to a different source or target: delete it and create a new one. Use this, not hadron_update_node(edges:), which replaces the node's whole edge set. edgeRef (ID or edge URN hrn:edge:<root>:<memory>:<loc>); any of name, loc, description, isRunnable, priority, condition, data
hadron_delete_edge Delete ONE edge. The source and target nodes and all their other edges are untouched. Use this rather than hadron_update_node(edges:) with the edge left out, which would delete the node's other edges too. edgeRef (ID or edge URN)
hadron_replace_text Search and replace text across many nodes in one call. The selection is explicit node URNs plus whole memories, optionally narrowed to a subtree by prefix (a parent loc; matches that node and its descendants on : boundaries, and needs memoryUrns). It searches the chosen fields (content, name, alias, description, abstract, tags), never JSON fields. The match is literal unless regex is true. Run with dryRun: true first. Governed nodes and Channel addresses are skipped and reported. A multi-node run is all-or-nothing: if one node's edit would break a field cap, such as the 2000-character abstract cap, the whole batch is refused before any write. Each change keeps revision history and re-embeds the node. oldText, newText, fields; nodeUrns and/or memoryUrns; optional prefix, caseInsensitive, regex, dryRun
hadron_create_task Create a RUNNABLE node, a task that hadron_run_task can execute. This is the only way to author one: hadron_create_node refuses a write that would produce a runnable node, because writing something the platform will execute is a different act from writing prose. The runnable flag is set by the tool. urn, name; optional description, abstract, content, tags, nodeType, seq, properties, data
hadron_update_task Edit an existing runnable node. hadron_update_node refuses any edit whose result is still a runnable node, including a prose-only one, so this is the door. Omitted fields are kept. Pass isRunnable: false to retire the task. urn; any of the hadron_create_task fields; optional expectedRevision, isRunnable
hadron_create_review Create a REVIEW node, a check on work performed. Reviews are not coding-specific and may be a safety check, which is why hadron_create_node refuses to author one. The role is review by default, or a dotted sub-role such as review.security. urn, name; optional role, description, abstract, content, tags, nodeType, seq, properties, data
hadron_update_review Edit an existing review node. hadron_update_node refuses any edit whose result is still a review, so a safety check cannot be rewritten through the generic surface. Omitted fields are kept. Pass role: null to retire the node from the review kind. urn; any of the hadron_create_review fields; optional expectedRevision
hadron_list_recovery_nodes List the retained deleted nodes in one live memory. You need read and write access to the memory. Ordinary reads return live nodes only. memoryRef (ID or qualified URN); optional limit (default 20, maximum 200), offset (default 0)
hadron_get_recovery_node Read one retained deleted node's stored body, in a live memory you can read and write. Templates and includes are not expanded. nodeRef (stable ID or qualified URN)
hadron_list_recovery_edges Inspect live edges and accessible deleted endpoints in one memory you can read and write. Endpoints you can't access are left out of both the page and the total. An edge may have no name. memoryRef; optional limit (default 20, maximum 200), offset
hadron_restore_node Restore one retained deleted node in a live memory you can read and write. Restore deleted ancestors first. Governed nodes, comments, compiled boot prompts and protected internal addresses refuse. It does not restore descendants or revisions. nodeRef; optional session

seq on message nodes. hadron_create_node and hadron_update_node refuse ([seq_protected] on MCP, SEQ_PROTECTED on GraphQL) a seq that sets or changes the order of a chat message: a node whose nodeType is chat-message or record, before or after the write, outside a Channel. Refused: a seq that differs from the stored one (null included); a create, or a retype into one of those types, that carries a seq; and restoreNodeRevision on such a node when the restored revision's seq differs from the stored one (restoring an equal seq is allowed). Not refused: a content edit that names no seq, a seq equal to the stored one, and a write where both the stored and the resulting type are ordinary (the default type here is info). The refusal applies to every principal. A node under a Channel's address is still refused LOC_PROTECTED first. The rule is cor:dmo:090:02 (hrn:node:hadronmemory.com:specs:cor:dmo:090:02). Run tools default to record, so the same refusal reaches runs that pass seq: see Multi-node runs.

Replacing vs. merging data. hadron_create_node and hadron_update_node write the data bag wholesale — the object you pass becomes the node's entire data. hadron_update_node_data merges instead: it overlays your patch's top-level keys onto the existing data (patch wins on collision) and leaves the rest intact. Reach for it when you want to set one or two keys without re-sending the whole bag. The replace and merge tools cross-reference each other so an agent picks the right one. The merge honors the same write-permission, encryption, and revision-history invariants as a normal write.

edges on hadron_create_node / hadron_update_node is an array of edge objects. Each edge object can include targetId (or loc/URN), plus optional name, description, loc, and isRunnable. Passing edges replaces the source node's full edge set. Use hadron_create_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; hadron_validate will flag it later.

objectType on hadron_create_node / hadron_update_node tags a node as a member of a schema collection (e.g. competitor), orthogonal to nodeType. On a memory that has a schema, the write is validated against the declared collection — a violation is returned as a Schema violation: error. On an unschema'd memory objectType is free-form.

What a move does to name. Nothing, by default. A node's name is its human-authored display title and survives a move, whether you arrive through hadron_move_node or the GraphQL moveNode mutation. Pass renameToLeaf: true to also re-derive the name from the destination loc's last atom (services:db-helper → db-helper); that overwrites the existing title, so pass it only when the name is meant to track the loc. Descendants' names are never rewritten either way — only their loc prefix changes.

Changed in hadron-server #1017

Before that fix the MCP tool rewrote name on every move, silently and with no way to decline, while moveNode did not. If you carry a habit of re-setting the name after each move, you can drop it — doing so now overwrites a title the platform just preserved.

Moving a subtree across memories. hadron_move_node relocates a node together with its entire loc-subtree — every descendant whose loc is prefixed by <loc>: moves too, and their URNs follow the parent. When targetUrn names a different memory, the whole subtree relocates there: the moved nodes carry their embeddings (re-indexed under the destination memory's policy), and outgoing edges whose source moved are rewritten into the destination. An edge to a node left behind becomes a cross-memory edge, whose far endpoint is access-gated on read (so a reader who can't see the other memory gets null for that edge's source/target). Cross-memory moves are refused (a BAD_USER_INPUT-class error) for a documented safe subset:

  • either the source or the destination memory is encrypted,
  • the subtree contains a chat-root node (its data.scope ties it to the memory class), or
  • a moved node would violate the destination memory's schema.
  • the subtree has live comment threads and the destination is a private or system memory, which take no comments. This one carries its own typed code, COMMENT_MOVE_UNCOMMENTABLE in extensions.code (not BAD_USER_INPUT), naming the nodes and their comment counts. Otherwise a commented node's threads move with it. See Comment on a node.

Git-backed memories are not on that list. A move touching one used to be refused, on the grounds that it reached only the database and the next repo-wins sync would re-mint the moved rows from the stale source files. The move is mirrored instead: the moved nodes' files are removed from the source repository and written to the destination's. Git is one integration of a memory, not a lock on it. Like every git mirror this is best-effort — a repository that is unreachable leaves the database authoritative, exactly as it would for an ordinary edit.

A collision at the target loc (or any descendant slot) refuses the move with URN_ALREADY_EXISTS unless you pass overwrite: true (which soft-deletes the explicitly-named target first). A same-memory move leaves existing edge locs untouched.

Comments

Feedback beside a node, in threads, that never changes the node itself: not its content, revision, approval or mint state. Comments are never approved or minted. See Comments: feedback beside knowledge and Comment on a node.

Tool Purpose Key inputs
hadron_list_comments Read a node's discussion: its threads, newest first, each with its oldest 200 replies. Needs read access to the node's memory. A thread with more replies ends with … N more replies not shown: offset pages threads, not replies, so those replies can't be listed (hadron_get_comment reads one whose URN or id you already have). targetRef (URN or id); optional state (an array: ["OPEN"], ["RESOLVED"] or both; default all), limit (default 20, cap 200), offset
hadron_get_comment Read one comment. commentRef (URN or id)
hadron_create_comment Start a thread on a node. Needs write access to the node's memory, which must be an app, knowledge, personal or group memory. You hold at most one open thread per node. targetRef, body (markdown, up to 20,000 characters); optional quote (plain text from the node, up to 2,000), anchorRevision (default: the node's current revision)
hadron_reply_to_comment Reply in a thread. Any comment of the thread works as commentRef, as long as the thread's top-level comment isn't a deleted stub ([comment_deleted]). A resolved thread accepts replies and stays resolved. commentRef, body
hadron_edit_comment Edit your own comment. A comment keeps no revision history: the earlier text is not kept. The edit sets the comment's editedAt and editedBy. commentRef, expectedRevision; optional body, quote (null clears it)
hadron_delete_comment Delete a comment: your own, or, if you manage the memory, anyone's. A top-level comment that still has live replies stays as a stub with no text; any other comment is no longer shown at all, and a stub goes with its last reply. Either way it no longer counts as an open thread. commentRef, expectedRevision
hadron_resolve_comment_thread Mark a thread resolved. Name its top-level comment. Any writer of the memory may. commentRef, expectedRevision
hadron_reopen_comment_thread Reopen a resolved thread. Any writer of the memory may. Refused when the thread's author already has another open thread on the node. commentRef, expectedRevision
  • Every read is labeled as feedback. The comment tools' output says that comments are feedback from readers, not part of the node's content and not authoritative.
  • Search leaves comments out unless you ask. hadron_find_nodes takes nodeKind: CONTENT (the default, content nodes only), COMMENTS (comment nodes only, found exhaustively in every mode before ranking and limits) or ALL. Every comment hit is labelled as a comment. This is GraphQL's NodeFilter.contentScope; it's unrelated to hadron_get_node's contentScope, which picks the parts of one node to return.
  • Node reads carry a cue. hadron_get_node on a node with comments adds a line such as Feedback: 1 open thread, 0 resolved, 2 comments — reader feedback beside this node, not part of its content (read with hadron_list_comments). On a comment node read through the generic tools, the line says it is a comment instead.
  • Refusals are typed. A refusal reads [<code>] <message>, followed by its details as key: value lines: for example [comment_open_thread_exists] with the existing threadId, or [node_write_conflict] with currentRevision. The codes are the GraphQL ones, lowercased.
  • Authorship. In a worker session started with hadron_start_session, the comment is authored by that worker. Otherwise it's authored by you, with the agent behind the call when the server can attribute one.
  • Who may delete. hadron_delete_comment is the GraphQL deleteComment: its author (with write access), or a memory manager: the memory's owner, or an owner or admin of the owning organization, or a platform admin (never in a personal memory). Anyone else gets [comment_not_author]. Deleting a whole thread at once is a separate memory-admin operation (deleteCommentThread), available in GraphQL and not as an MCP tool. There is no hide or retract.
  • Generic node tools refuse comments. hadron_create_node and hadron_update_node refuse to create a comment or turn a node into one (ROLE_GOVERNED). See Node types.

Signatures

Ask a person to sign a node's current title, abstract and content with their passkey, and read how the request ended. No tool takes or produces a signature: the person signs on a Hadron-hosted page. See Signed revisions.

These tools are registered only on a deployment where signing is switched on (PASSKEY_SIGNING_ENABLED=true). Where it is off, they do not appear. The same requests are available from the CLI as hadron node sign and hadron node signing-request; see Hadron CLI.

Tool Purpose Key inputs
hadron_request_signature Create a signing request that pins the node's current revision. Any reader of the node may ask, agents included. The receipt carries the ceremony link and ends with The signer signs on the server-hosted ceremony page; no agent can complete this request. nodeRef (URN or id); optional expectedRevision (refused unless still current), signer (a user id to name as the only signer, who must be able to write the memory; omitted, any writer of the memory may sign)
hadron_get_signing_request Read a request's state and, once it's completed, its signature. Visible to the node's readers. An unknown id and one you can't read give the same answer: [signing_request_not_found] Signing request not found. id
hadron_withdraw_signing_request Withdraw an open request. Only the account that asked may, from any of its sessions or workers. id

All three print the request in the same shape:

Signing request <id>
State: <open|completed|declined|expired|stale|withdrawn> (ended <time>)
Node: <node URN> at r<revision>
Signer: <named signer's URN, or "any writer of the memory">
Expires: <time>
Ceremony link: <URL>
Signature: <state> by <signer URN> (r<revision>, "<passkey label>") at <verified time>

The (ended …) part appears once the request has ended. The Ceremony link: line appears only while the request is open: hand that URL to the person who should sign, copied verbatim and never composed. The Signature: line appears only on a completed request whose signature verifies.

  • A request ends exactly once. It ends as completed, declined, expired, stale or withdrawn. It expires after the deployment's SIGNING_REQUEST_TTL_SECONDS, which defaults to 24 hours. A request past its deadline reads expired straight away, with the deadline as its end time. It goes stale when the node's title, abstract or content changes, or when its memory is encrypted. Tags and properties don't stale it.
  • Node reads carry a Signatures: line. hadron_get_node and hadron_get_nodes print it next to Approval:. The find, list and search tools don't.
    • With nothing to report, it reads Signatures: none.
    • On a node in an encrypted memory, it reads Signatures: not applicable (encrypted memory).
    • Otherwise it reads, for example, Signatures: 1 current — hrn:user:… (r3, "MacBook"); 2 earlier. Current and pending signatures name their signer, revision and passkey label. A pending one adds first passkey in its window. Earlier and cancelled ones are counted, not named.
    • A stored signature that fails re-verification is appended as · 1 integrity problem (a signature record failed verification), never listed as a signature.
  • GraphQL is the same surface. The tools call requestNodeSignature, signingRequest and withdrawSigningRequest, so refusals and permissions match exactly. See the generated GraphQL schema for Node.signatureStatus, Node.signingRequests (a node's requests) and the signingRequest query (one request by id).
  • Refusals are typed, as [<code>] <message> followed by key: value detail lines, the same as the comment tools. Creating a request is refused with:

    Code When
    node_not_found The node doesn't exist, or you can't read it.
    encrypted_memory_not_applicable The node is in an encrypted memory.
    comment_not_signable The node is a comment.
    revision_mismatch expectedRevision is no longer current (details: expected, current).
    node_is_placeholder The node is a reserved placeholder.
    signer_not_found signer names no user.
    signer_not_a_writer The named signer can't currently write the node's memory.

    Write access is checked again when the signer signs or declines, so a signer who loses it after the request is made can't complete it.

    Withdrawing is refused with signing_request_not_found, signing_request_not_requester (you're not the account that asked), or signing_request_ended (details: state). Creating and withdrawing are refused with [forbidden] while you're impersonating someone.

Object store

The object-store tools are the record-oriented surface over structured storage: an object is a node with an objectType, presented as a flat record { id, type, ...fields }. id and type are the reserved envelope; loc/name are auto-derived and hidden. This is the friendly path for typed records — reach for it instead of the node tools when you're doing CRUD on collection members. See Object store API for the full contract.

Tool Purpose Key inputs
hadron_create_object Create a record in a collection. Fields are validated against the memory's schema when the collection is declared. memoryUrn, type, fields; optional key (natural id), name
hadron_get_object Read one object by id or node URN as { id, type, ...fields }. ref
hadron_update_object Shallow-merge fields into an object (atomic; patch wins, unmentioned fields kept), then re-validate. ref, fields; optional reason
hadron_delete_object Delete an object — soft by default; hard: true removes the row. Non-recursive. ref; optional hard
hadron_find_objects Query one collection → { objects, total }. memoryUrn, type; optional match, where, sort, limit, offset

hadron_update_object merges (unlike hadron_update_node, which replaces the properties bag). hadron_find_objects takes match (equality shorthand {field: value}, cast inferred from the schema), where (the full hadron_find_nodes predicate grammar, ANDed with match), and sort ({field: "asc"|"desc"}); it returns { objects, total }, where total is not a reliable count today (usually null, 0 for some empty results), so page with limit/offset until the page comes back empty; a short page is not the end. id and type are reserved and can't be field names.

Validate & run

Tool Purpose Key inputs
hadron_validate Walk a memory and report broken edges, missing content, stale abstracts, embedding failures, and property-schema conformance violations. memoryUrn (required, fully-qualified)
hadron_run_action Load an action-type node, resolve its dependencies, and execute it. loc; optional args (key-value object)
hadron_run_task Run a task (a runnable node) by loose name. Give task and optionally memory; the server resolves both against what you can read. An ambiguous or missing name returns a list to choose from, and urn runs a fully-qualified task directly. By default it RENDERS the task: it returns the assembled instructions, with {{arg}} substituted and dependencies inlined, for you to carry out. Pass appRef to EXECUTE it server-side instead: the server starts a manual App run and returns the run id to poll. An executed run is served as an installed Agent: omit agentRef and the App's single installed Agent serves it; pass agentRef (an Agent id or URN installed in that App) to name one. An App with several installed Agents and no agentRef is refused with the prefix [RUN_AGENT_REQUIRED] (Could not start run: [RUN_AGENT_REQUIRED] This App has several installed Agents: pass agentRef to name the one the run is served as.); an Agent that is unknown or not installed in the App is refused as BAD_USER_INPUT. agentRef only applies with appRef. task or urn; optional memory, args, appRef, agentRef, runAsSelf
hadron_get_run Read an App run you started or may read: its status, where it is or stopped (curNodeUrn), why it failed, what it extracted (data) and the path it walked (hops, one entry per completed hop). Pass the run id or hrn:apprun URN that hadron_run_task printed. A run you cannot read answers "not found", the same as one that does not exist. Read-only. ref
hadron_preview_automation Show the exact graph and its hash before you re-adopt an automation that has changed. Trigger refs are row IDs. triggerKind (SCHEDULE, WEBHOOK or MANUAL), triggerRef
hadron_re_adopt_automation Re-adopt a trigger using the hash from hadron_preview_automation. Only the run-as user can adopt their own automation. triggerKind, triggerRef, expectedHash (64 hex characters)

hadron_validate is safe to run any time — it's a read-only sweep. It takes the memory to check as memoryUrn (fully-qualified). On a memory with a structured schema it also reports nodes whose objectType/properties violate the schema — the non-retroactive backstop for records written before the schema existed. hadron_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.

App grants

One tool, and it is present only where the deployment has signing switched on (PASSKEY_SIGNING_ENABLED). Its full rules, and the GraphQL calls that list, revoke and withdraw, are in App grants.

Tool What it does Inputs
hadron_create_grant Ask for a grant in an App you manage, as yourself: never as a worker, even on a worker-bound connection, so the row records you and no worker or session. The grant is born pending and allows nothing until a person signs it. The holder is a worker of the App or an agent installed in it. app, action, values, holderKind (WORKER or AGENT), holderRef, reason (all required); optional startsAt, expiresAt (ISO times), maxUses

Refusals come back in lower case, each before any write: grant_not_manager (not a person who manages the App, and an unknown App: the same answer; an App key, a run, an impersonated session and a refused session binding get it too), grant_holder_not_allowed, grant_action_unknown, grant_values_invalid and grant_terms_invalid. Listing, revoking and withdrawing a grant are not available over MCP.

Chat

There are no MCP tools for driving a chatbot agent's chat. The eleven hadron_chatbot_* tools that once did — start, send, process, the routing map, route history, the goal stack, training entries and test personas — were removed in hadron-server#1143. The chat runtime itself is unchanged: drive it through the Chat API (GraphQL) or the portal.

The team chat and Channels are a different feature, and they are not on MCP either: see Former agent-team MCP tools.

Former agent-team MCP tools

The agent team works through the CLI and the portal, and MCP carries agents, not workers. The 71 tools below were disabled by hadron-server#3208 (99246d46; the plan is plans:mcp-team-cut): tools/list omits them for every principal, and a call answers the SDK's unknown-tool error, exactly like a name that never existed. Everything they did is still served by GraphQL, which the CLI and the portal call. Commands are checked against the hadron CLI v0.35.0 help, and the portal column names a page only where that page exists today, so it is not a claim of full portal parity.

The kept tools are the three session tools above, the four agent-definition tools and every core tool on this page. The specs that name a disabled tool keep their MCP part, marked "not planned to build"; the cut is reversible in the server code.

Former tool CLI Portal
hadron_resume_session hadron team session start (no worker named) none
hadron_create_resume_claim hadron team session resume-claim none
hadron_record_work hadron team session log none (the worklog tables on the App page and the worker page only show existing records)
hadron_team_work_items hadron team session list the worklog table on the App page and the worker page
hadron_cast_worker hadron team worker cast the cast form on the App page
hadron_list_workers hadron team worker list the staff list on the App page; the roster on the tasks page
hadron_get_worker hadron team worker get the worker page (/app/workers/[id])
hadron_update_worker hadron team worker update the worker page (signature and trailer only)
hadron_delete_worker hadron team worker rm the delete-worker dialog on the App page
hadron_change_worker_agent hadron team worker change-agent none
hadron_set_worker_reports_to hadron team worker set-reports-to none (the worker page shows who a worker reports to)
hadron_list_channels hadron channel list the Channels page (/app/apps/[appId]/channels)
hadron_create_channel hadron channel create the Channels page
hadron_register_list hadron channel register list the register panel on the Channels page
hadron_register_add hadron channel register add the register panel on the Channels page
hadron_register_remove hadron channel register rm the register panel on the Channels page
hadron_channel_post hadron channel post the Channel chat on the App page
hadron_channel_read hadron channel read the Channel chat on the App page
hadron_team_chat_post hadron team chat post the team chat on the App page
hadron_team_chat_read hadron team chat read and hadron team chat check the team chat on the App page
hadron_team_chat_search hadron team chat search (and hadron channel search for a Channel) the team chat search on the App page
hadron_team_chat_mark_read hadron team chat mark-read none
hadron_team_chat_inbox hadron team chat inbox none
hadron_team_chat_inbox_ack hadron team chat inbox (it acknowledges after it prints) none
hadron_team_attention none: hadron team attention is retired (hadron-server#2027); read your chat with hadron team chat read none
hadron_team_attention_page none: retired with hadron team attention (hadron-server#2027) none
hadron_team_attention_switchover none: hadron team attention switchover is retired (hadron-server#2027) none
hadron_task_create hadron team task create the new-task page (/app/apps/[appId]/tasks/new)
hadron_task_update hadron team task update the task page (/app/apps/[appId]/tasks/[taskId])
hadron_task_assign hadron team task assign the task page
hadron_task_reassign hadron team task reassign the task page
hadron_task_blocker_add hadron team task add-blocker the task page
hadron_task_blocker_remove hadron team task remove-blocker the task page
hadron_task_priority_set hadron team task set-priority the task page
hadron_task_start hadron team task start none
hadron_task_progress hadron team task progress none
hadron_task_finish hadron team task finish none
hadron_task_cancel hadron team task cancel the task page
hadron_task_park hadron team task park the task page
hadron_task_make_ready hadron team task ready the task page
hadron_task_get hadron team task get and hadron team task tree the task page
hadron_task_list hadron team task list and hadron team task mine the tasks page (/app/apps/[appId]/tasks)
hadron_team_events hadron team events none
hadron_alarm_ack hadron team alarm ack none (the tasks page lists open alarms)
hadron_team_roster hadron team roster the roster on the tasks page
hadron_team_availability hadron team availability get none
hadron_worker_availability_set hadron team availability set --worker none
hadron_model_family_availability_set hadron team availability set --family none
hadron_stall_schedule_get hadron team stall-schedule get none
hadron_stall_schedule_set hadron team stall-schedule set none
hadron_stop_signal_set hadron team stop set the stops page (/app/apps/[appId]/stops)
hadron_stop_signal_lift hadron team stop lift the stops page
hadron_stop_signal_list hadron team stop list the stops page
hadron_set_team_pause hadron team pause (and hadron team resume) none (a worker's own pause is on the App page)
hadron_isolate_worker none: worker isolation is retired (hadron-server#2130, ruling A) and hadron team isolation was removed in CLI v0.41.0 none
hadron_clear_worker_isolation none: retired with hadron team isolation none
hadron_ticker_list hadron ticker list the tickers page (/app/apps/[appId]/tickers)
hadron_ticker_create hadron ticker create the tickers page
hadron_ticker_update hadron ticker update the ticker page (/app/apps/[appId]/tickers/[tickerId])
hadron_ticker_delete hadron ticker delete the ticker page
hadron_ticker_subscribe hadron ticker subscribe none
hadron_ticker_unsubscribe hadron ticker unsubscribe none
hadron_worker_wake_settings hadron team wake-settings get and hadron team wake-settings set reading: the wake-ups panel on the worker page; pausing: the App page
hadron_due_wakes hadron team wakes due none
hadron_ack_wakes hadron team wakes ack none
hadron_delivery_settings_get hadron team delivery-settings get the delivery settings panel on the tickers page
hadron_delivery_settings_set hadron team delivery-settings set the delivery settings panel on the tickers page
hadron_agent_ticker_template_list none (hadron ticker apply-templates applies an Agent's templates; nothing lists them) none
hadron_agent_ticker_template_create none none
hadron_agent_ticker_template_update none none
hadron_agent_ticker_template_delete none none

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
hadron_list_apps List the Hadron Apps the caller has access to, each with its canonical URN and the caller's role on it. (none)
hadron_set_active_app Pin an App as the active scope. Subsequent App-scoped calls (hadron_list_memories, hadron_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.

Organization selection

Tool Purpose Key inputs
hadron_set_active_org Set — or with clear: true drop — the active organization: the tenancy an org-scoped read, such as a global search, runs against. Persisted per client instance, like the active App. org (hrn:org:<root> or id — one you are a member of), or clear: true

You need it only when you belong to several organizations. The organization is taken from the first of: an org named in the call › the active App's organization, when that App is org-owned (a personal App has none) › this selection › your single membership › with no membership at all, your own user-owned memories. With two or more memberships and none of those, an org-scoped read refuses with ORG_REQUIRED and lists your memberships. A foreign or nonexistent org reads the same (org_not_found). App-key callers carry their organization in the credential and cannot use this tool. hadron_server_info reports the organization currently resolved, and which rung chose it.

Selecting an organization is not a search scope and attaches nothing: the organization picks the tenancy, a scope picks the view.

Server identity

Tool Purpose Key inputs
hadron_server_info Return the deployment URL, the version, the capability tokens this build carries, and whether this connection was re-established. Useful when a caller has multiple MCP namespaces wired up and needs to know which one a tool call landed on — and to check a feature is present before relying on it. (none)

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

The deployment-switch tokens on this line (node-signing, grant-signing, passkey-registration) can also be read without MCP or sign-in, from GET /capabilities.

server: https://srv.example.com
version: <surface-contract version, illustrative>
capabilities: app-selection, reconnect-notice, client-session-state, active-org
connection: re-established (the previous MCP session ended; any active App or
            active memory selection was reset)

This is an illustrative sample, not a snapshot to copy. node-signing, grant-signing and passkey-registration appear on the capabilities: line only on a deployment that has switched them on, and new tokens appear as features ship.

Test for a token; never compare version numbers (cor:api:220:01). The version: identifies the surface contract, not the deployed build, and it does not tell a client which features are present. It moves when a caller could detect a change, but it is not the feature test. Tokens are named per feature, so they answer the question a client actually has — "can I select an organization here?" (active-org) — which a release number only answers if you also know which release introduced it. The tool inventory is useful for diagnosis, but the tokens are the contract: test those.

Worker binding and team coordination are not on this line. They go through the CLI or the portal, and a build with no worker-model token is the normal case. A worker session the CLI created can still attribute core MCP calls to that worker through X-Hadron-Session or session; see Sessions.

What you see What it means
The token you need The feature is on this build. Use it.
No such token Fall back — take another route, or decline and say why. Do not proceed hopefully.
No capabilities: line at all A build predating the mechanism. Assume nothing it has not otherwise confirmed.

Tokens are additive and permanent while the behaviour is honoured, so they are safe to depend on. A feature that is removed on purpose loses its token, and that is a breaking change for every client that tested for it. The vocabulary is not frozen — new tokens appear as features ship.

Why this is not paranoia. MCP silently drops arguments a build does not recognise. A deployment behind the docs accepted hadron_start_session without workerRef, returned a healthy-looking session that was never bound to a worker, and quietly broke provenance for everything that session produced. The attempt succeeded either way, which is why probing cannot substitute for asking.

A connection: re-established line means this session replaced an earlier one and your selections were reset — unless you send X-Hadron-Client-Id, in which case they are restored instead. The notice names only the active App and the active memory, but the active scope and active organization reset too, so after a reconnect a search can run on a different rung of the search ladder. Check the scope line on the next result.

Stability and changes

Most of the MCP tool surface is stable: the names and core signatures of the tools that remain have not churned, and new tools are additive. Removals are breaking changes, and two have happened on purpose: the hadron_chatbot_* tools (hadron-server#1143) and the agent-team tools (hadron-server#3082). A removed feature loses its capability token; the chatbot and team surfaces now live in the Chat API, the CLI and the portal.

If a tool you call returns an unexpected error, call hadron_server_info before assuming a regression: check that the deployment carries the capability token for the feature, and whether the connection: line says this session replaced an earlier one. Both are commoner causes than a broken tool, and both are visible in one call.

Release notes tell you what changed in a release; the tokens tell you what this deployment can do, which is the question you actually have.