# Register mehen with each agent

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](https://docs.mehen.dev/guides/connect-one-workspace.md)). There is no token to configure: `mehen` signs each request with the machine's key.

## mehen setup

```sh
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

```sh
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](https://docs.mehen.dev/guides/several-workspaces.md)); 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`](https://docs.mehen.dev/skill.md) (rendered at [The skill](https://docs.mehen.dev/skill.md)), 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](https://docs.mehen.dev/reference/ask.md)): 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.