MCP tools

Agents → MCP tab — lists hal0’s hosted MCP servers (bundled + any installed) with live tool counts and one-click “add to Claude/Codex/Cursor” config; expand a server to see each tool’s read-only / gated / destructive badge. Pending approvals live in the separate approval inbox reachable from the top bar, not on this tab.

hal0 hosts two Streamable-HTTP MCP servers that agents call: a focused memory server (/mcp/memory) and a full admin server (/mcp/admin). Every admin tool is classified into one of three tiers — autonomous-read, autonomous-write, or approval-gated. Gated tools enqueue for owner approval before they run; autonomous tools execute immediately.

Note

hal0 has no built-in auth (ADR-0012) — there are no bearer tokens. When Hermes or another bundled agent calls the MCP server, it identifies itself with the X-hal0-Agent header (set from $HAL0_AGENT_ID by the agent wrapper). The server stamps that identity on every audit row and carries it onto the internal REST call, so an agent’s actions are attributed and gated by its identity, not a secret. Each tool call is written to the audit log.

Memory MCP (/mcp/memory)

Hindsight-backed long-term memory. The memory subsystem is opt-in — these tools only function when the server is started with HAL0_MEMORY_ENABLED=1; otherwise calls degrade to a no-op / unavailable surface.

Tool	Tier	Effect
memory_add	autonomous-write	Write one item → {id, timestamp} (+ operation_id when async).
memory_search	autonomous-read	Vector + tag + time-window query → {results}.
memory_recall	autonomous-read	Token-budgeted consolidated recall (Hindsight preferred) → {results}.
memory_list	autonomous-read	Paginated walk → {items, next_cursor}.
memory_delete	conditional	Remove by id(s) → {deleted}. Autonomous for one id; gated for >1.

Notable arguments:

• dataset defaults to shared; private-mode callers promote to private:<client_id>. A search may pass a list of datasets.
• source is server-injected from the caller’s identity and cannot be supplied by the caller (audit grounding).
• document_id reuse upserts one logical document (e.g. an evolving conversation); it must match the identity grammar (alphanumeric / - / _, ≤ 64 chars).
• memory_recall accepts max_tokens (default 4096, range 1–32768), types, dataset, and tags for token-budgeted retrieval via Hindsight recall.

Admin MCP (/mcp/admin)

The admin server hosts every tool an agent might call, including the memory_* tools above (delegated to the memory surface). Tools are classified as follows.

Autonomous read

Execute immediately; pure reads against the local REST or host surface.

Tool	Effect
slot_list	List every slot known to hal0 (local + remote).
slot_status	One slot’s lifecycle state + metadata.
model_list	Aggregate models from local registry + upstreams.
hardware_probe	Live hardware probe — backends, memory, accelerators.
capability_list	Capability overlay state — backends + selections.
provider_list	List configured providers.
version_info	hal0 version + runtime status.
stack_list	List every stack, with the active stack + drift status.
stack_status	One stack’s detail, active flag, and drift status.
profile_list	List every profile in the catalog (seed + custom).
profile_status	One profile’s resolved detail (image, flags, backend, used-by).
profile_export	Export a profile to a portable .hal0profile.json envelope (no secrets/host paths). A POST under the hood, but read-shaped — no state change.
gpu_target_version	Decode KFD’s gfx_target_version to a gfxNNNN string.
npu_status	XDNA NPU presence + driver binding.
env_report	Composite host snapshot (container, CPU, RAM, GPU, NPU, …).
model_store_probe	Probe a model-store path (fstype, free/total, writable, UMA).

Autonomous write

Mutating but reversible, scoped, and low blast-radius.

Tool	Effect
model_swap	Hot-swap the primary slot to a new model.
memory_add	Add an item to long-term memory.
memory_search	Search long-term memory.
memory_list	Page through long-term memory items.
memory_delete	Delete memory item(s) — autonomous only for a single id.

Gated (require approval)

Always enqueued for owner approval before execution. These are the members of GATED_TOOLS:

Tool	Effect
model_pull	Pull a model into the local registry.
model_delete	Delete a model from the local registry.
slot_create	Create a new slot.
slot_delete	Delete a slot.
slot_restart	Restart a slot’s systemd unit.
capability_set	Assign a capability child to a slot.
config_write	Update hal0.toml top-level settings.
provider_credential_write	Write provider credentials (secrets never echoed).
stack_apply	Apply a stack — commit its slot config and converge the running slot set to match.
stack_import	Import a stack from a .hal0stack.json envelope.
stack_delete	Delete a custom stack from the catalog.
profile_import	Import a profile from a .hal0profile.json envelope.
profile_delete	Delete a custom profile from the catalog.
logs_tail	Tail journald for one systemd unit.
memory_delete (bulk)	Delete more than one memory id in a single call.

Stacks and profiles are gated the same way slots are: applying or importing a stack reconfigures the whole inference surface (it can load, swap, or unload every slot at once), and importing or deleting a profile mutates the shared catalog — both mirror the blast radius of slot_create/capability_set.

Note

logs_tail is gated as a defensive measure: journald lines can carry Bearer tokens and provider keys, so an agent dumping raw logs is a potential exfiltration vector. Secret tokens in the returned lines are redacted before the response leaves the MCP process.

A gated call returns {"status": "pending_approval", "approval_id": "..."}. The owner approves or denies it from the dashboard approval inbox, the /api/agent/approvals surface, or the hal0 agent approvals CLI.

See also

• REST API index — the /api/* routes each MCP tool forwards to.
• Devices, providers & profiles.
• Capabilities & profiles — what the profile_* tools operate on.
• Stacks and Manage slots — Stacks — what the stack_* tools operate on.
• Connect an MCP client — connecting an external MCP client to these servers.