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:
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 Notesbecomesmy-notes).memoryClass—knowledge(default),group,personalorprivate.org— organization URN or id. Required forknowledgeandgroup.shortDescription,description,tags— optional descriptive fields.visibility—PUBLIC,ORGANIZATIONorGROUP. A knowledge memory takesPUBLICorORGANIZATION(defaultORGANIZATION); a group memory is alwaysGROUP;personalandprivatetake 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_sessionrefuses aworkerRefor alaunchGrantwithMCP_WORKER_BINDING_UNSUPPORTEDbefore 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
sessionargument of a write, or send its id in theX-Hadron-Sessionheader, 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 ownsorKind: 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>andRead 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:
- a
scopenamed in the call; - the active scope (
hadron_set_active_scope); - the active App —
app, its attached memories; - the active organization —
global, see Organization selection; - 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.scopeties 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
privateorsystemmemory, which take no comments. This one carries its own typed code,COMMENT_MOVE_UNCOMMENTABLEinextensions.code(notBAD_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_nodestakesnodeKind:CONTENT(the default, content nodes only),COMMENTS(comment nodes only, found exhaustively in every mode before ranking and limits) orALL. Every comment hit is labelled as a comment. This is GraphQL'sNodeFilter.contentScope; it's unrelated tohadron_get_node'scontentScope, which picks the parts of one node to return. - Node reads carry a cue.
hadron_get_nodeon a node with comments adds a line such asFeedback: 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 askey: valuelines: for example[comment_open_thread_exists]with the existingthreadId, or[node_write_conflict]withcurrentRevision. 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_commentis the GraphQLdeleteComment: 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_nodeandhadron_update_noderefuse 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,staleorwithdrawn. It expires after the deployment'sSIGNING_REQUEST_TTL_SECONDS, which defaults to 24 hours. A request past its deadline readsexpiredstraight away, with the deadline as its end time. It goesstalewhen 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_nodeandhadron_get_nodesprint it next toApproval:. 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 addsfirst 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.
- With nothing to report, it reads
- GraphQL is the same surface. The tools call
requestNodeSignature,signingRequestandwithdrawSigningRequest, so refusals and permissions match exactly. See the generated GraphQL schema forNode.signatureStatus,Node.signingRequests(a node's requests) and thesigningRequestquery (one request by id). -
Refusals are typed, as
[<code>] <message>followed bykey: valuedetail lines, the same as the comment tools. Creating a request is refused with:Code When node_not_foundThe node doesn't exist, or you can't read it. encrypted_memory_not_applicableThe node is in an encrypted memory. comment_not_signableThe node is a comment. revision_mismatchexpectedRevisionis no longer current (details:expected,current).node_is_placeholderThe node is a reserved placeholder. signer_not_foundsignernames no user.signer_not_a_writerThe 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), orsigning_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.
Related¶
- Connecting an MCP host — end-to-end walk-through of pointing Claude Code at a Hadron memory.
- Install Hadron with the install script —
one-liner to wire
.mcp.jsonand the Spec Kit extension. - Adding nodes to a memory —
how
hadron_create_nodeinteracts with the portal's auto-slug and validation rules. - Conversation routing — model behind
the
hadron_chat_*tools. - Chat API — the GraphQL side of the same chat-driving surface.
- MCP App selection — full reference for
hadron_list_appsandhadron_set_active_app.