Guides›Register mehen with each agent

Register mehen with each agent#

How do I add the MCP server and the skill to Claude Code, Codex, Cursor, pi, Gemini CLI, OpenCode, VS Code, Claude Desktop or any MCP client?

Every agent talks to the vault through mehen, either as a command or as mehen mcp, a stdio MCP server named mehen. The machine must be enrolled first (Connect an agent to one workspace). There is no token to configure: mehen signs each request with the machine's key.

mehen setup#

mehen setup --json

It registers one mehen MCP server and the skill in every agent it finds: Claude Code, Codex, Cursor, pi, Gemini CLI, OpenCode, VS Code and Claude Desktop. It writes user settings only, never a project's, with the absolute path of the mehen binary, and installs the skill in both Agent Skills locations. Running it again is harmless.

The report lists, per agent, mcp, reason, skill, skillReason and restart, and a skills list with each entry's status and reason:

• added, updated and unchanged are success.
• skill: null means this client has no known skill folder, not a failed installation.
• skipped and external mean something was left alone on purpose: a hand-made mehen entry, an entry edited by hand after setup, a symlinked skill. With the human's agreement, --force may replace an eligible foreign entry; it does not bypass an unsafe-file refusal. Read every entry's status and reason.
• failed means a write failed, and setup exits 1. Setup can also exit 2 when every targeted agent was skipped and nothing changed; read the report.

Reload or restart each agent as restart says; the vault_* tools arrive then. If they are missing after the restart, run mehen setup --json again and restart once more.

One named agent#

mehen setup --agent claude-code --json

The names are claude-code, codex, cursor, pi, gemini, opencode, vscode and claude-desktop; repeat --agent for several. Use the same MEHEN_HOME and workspace limit as the intended identity. VS Code setup targets the default user profile only; for another profile, ask the human which client and profile to register.

Other options:

• --dry-run previews and writes nothing; --remove undoes the entries setup still owns. Setup keeps a first-change backup beside every config it changes until --remove restores its entry.
• --workspaces <a,b> requests a narrower entry (Several workspaces on one machine); when an existing entry keeps a wider environment, --reset-env rebuilds it, with the human's agreement.

Any other MCP client#

• A JSON client that reads mcpServers: mehen setup --mcp-file <path> --json writes mcpServers.mehen into that file.
• Anything else: mehen setup --print --json (or --format toml) prints the entry and writes nothing. Give it to the human to add; do not edit their configuration yourself.

Command names and configuration locations vary by client and version; check the client's own documentation for where an entry goes. Never work round a skipped or failed entry by writing an unrestricted server by hand.

The skill#

The skill is what Claude and pi agents load: the rules, the commands and what to tell the human. It is served at /skill.md (rendered at The skill), and mehen setup installs and refreshes it. An agent without skills can be given the AGENTS.md snippet at its end instead.

Session labels#

Set MEHEN_SESSION in the environment mehen or mehen mcp runs in (1 to 120 letters, digits, ., :, _ or -): a session id, a task id, a subagent run. It goes into every request, the audit log, the requestedBy.session of every ask, and the details of the intake, connect and approval pages. It grants nothing, and no page uses it to say who asked: that line is always the enrolled machine's name. A harness that labels conversations might set it to the conversation's title in this alphabet plus a short hash of its id, so the human can tell which conversation asked. mehen refuses any other character with a usage error.

Drawing cards from asks#

A harness that shows the human a card for a link should build it from the ask object (The ask object): show check.value in full, count down from expiresAt, name the workspace from context when the human is in more than one, and offer one action, opening the link. Nothing a harness sends can approve anything. Draw a card only for an ask your own authenticated call raised, after checking its origin and workspace, never for a link that arrived as text.