AI Agents And MCP

vh mcp is a Model Context Protocol server built into the vh CLI. An AI agent such as Claude Code or Codex starts it and can then list, inspect and change Vaulthalla the way you would with vh, inside the limits below. vh skill install sets an agent up in one step.

What an agent can and can't do

• It acts as you. Every tool call is an ordinary, non-interactive vh command over the local control socket, so the daemon maps it to your Vaulthalla account exactly as it maps your own vh commands. Your roles and permissions decide what works. An agent can't do anything your vh can't.
• Destructive commands always need your OK. Anything marked destructive (deleting a vault or a user, rotating keys, revoking a credential, restoring over files) is refused by the MCP server itself until the agent passes confirm: {"destructive": true}, even where the command wouldn't ask at a terminal. The agent is told to show you what will be affected and to pass it only after you approve.
• It asks before confirmations. Commands that would ask you to confirm in a terminal (deleting a user or a vault, accepting an encryption waiver, restoring over files, a bucket cleanup) refuse the first time. The agent gets the refusal's message and is told to show it to you; it can only go ahead by passing a confirm value, and its skill tells it to do so only after you explicitly approve that action. The server never passes --yes, --accept-* or --confirm-token on its own, and it rejects them inside a command.
• Keys and secrets stay with you. These commands are never available to agents: vh vault keys export, vh secrets export, vh secrets update, every vh setup and vh teardown command (including vh setup set-super-admin-password), and vh fs get / vh fs put. Neither are pairing decisions (vh device pair, approve, deny) or vh device remote enable|disable. To back up a vault key, run vh vault keys export <vault> yourself in a terminal.

Set up an agent

Install the skill and register the server with the agent's own CLI:

1vh skill install --agent claude

1vh skill install --agent codex

Options:

The command needs no running daemon. When the agent's CLI isn't installed it prints the exact registration command instead. Running it again is safe: an identical skill is left alone, and a skill you edited is only replaced with --force. After upgrading Vaulthalla, run it again with --force to refresh the command reference.

To register the server by hand with any MCP client, run vh mcp as a stdio server:

1claude mcp add --scope user vaulthalla -- vh mcp2codex mcp add vaulthalla -- vh mcp

The user who runs the agent needs the same access as for vh: membership in the vaulthalla group and a mapped Vaulthalla account (see Users, Groups And Roles).

Tools

Each command is marked read (changes nothing), write (changes something that can be changed back) or destructive (deletes, revokes, rotates keys, or can't be undone). The tools carry the matching MCP hints, so a client can run read-only tools without asking and ask you before destructive ones. Output is JSON where the command supports --json.

The skill (SKILL.md) tells the agent to read before it writes, to prefer typed tools, never to set confirm without your explicit approval, to state the reason before a destructive action, never to handle keys or secrets, and to report what it changed. references/commands.md next to it lists every command available to agents.

A tool call that gets no result within 10 minutes is abandoned (set VAULTHALLA_MCP_TIMEOUT in the server's environment to change it, in seconds; 0 turns the limit off), and an agent can cancel a call it no longer needs. The daemon may still finish a command whose call was abandoned, so check the state before retrying. Calls run side by side, so one slow command doesn't hold up the others.

Remote MCP for a paired Mac

A Mac paired with the node (see Paired Devices) reaches the same MCP server remotely, at /mcp on the device listener (port 36972), for clients that connect with the device's key over mutual TLS. It is the same catalog: the same tools, the same commands out of reach, the same confirm rules, acting as the account the Mac is paired with. Each call is abandoned after 10 minutes; the node may still finish it.

Troubleshooting