Reference›Agent reference

Agent reference#

Which tools, templates and AGENTS.md lines does the skill point to?

The parts of the skill an agent looks up rather than keeps in mind: the MCP tools and their inputs, the templates by group, the per-agent setup commands and a snippet for a repo's AGENTS.md. The rules stay in the skill. The generated pages carry every detail: MCP tools, providers and templates and the ask object.

MCP tools#

Every tool except vault_templates also takes workspace? (a slug or id), needed when this server may use more than one workspace and neither the call nor the checkout decides:

• vault_status: mehen status --json, every workspace this server may use, each with its state; before any enrolment it is a success with next.command
• vault_doctor: mehen doctor --json, every check in one call with the next step; before enrolment too
• vault_templates (id?): mehen templates --json, no network
• vault_list (tag?, kind?, provider?)
• vault_show (item), with policySummary
• vault_check (item, method, url, headers?, body?): advisory; fetches public item metadata, sends nothing upstream and creates no approval
• vault_request (kind, name, reason, provider?, tags?, hosts?, paths?, injection?, new?, home?, project?): home defaults to private, which a machine with scope.privateCredentials false cannot use; pass home: "project" with project, or home: "workspace"
• vault_connect (provider, name, reason, client?, scopes?, expect?, requestClient?, clientTags?, new?, home?, project?)
• vault_fetch (item or run, method, url, headers?, body? or bodyBase64?, approval?, context? { project, environment }, select?, timeoutSeconds?)
• vault_env (env?, cwd?, check?): the cwd's mehen.toml selects the workspace; one outside what the server may use is workspace_not_allowed
• vault_wait (id of int_, apr_, con_, enr_, adp_ or pol_, timeoutSeconds? up to 600, default 45): finds the id in whichever workspace holds it; sends notifications/progress when the call carries a progressToken
• vault_pending: { pending: Ask[], notices? }, this machine's own asks in every workspace, each with its context, and its own notices when there are any
• vault_adopt_scan and vault_adopt_status: names and batch state for mehen adopt, never values
• vault_policy (action, item?, change?, reason?, proposal?, id?): read an item's policy (show) or stop your access (stop, cancel). Proposing or previewing a policy window is refused by the vault in this release (forbidden, "Policy widening is not available yet"): do not retry it, and never treat a policy window as a way round a protected context

Any result or error that hands over a link carries ask in structuredContent and a resource_link in content; isError stays true for approval_required, needs_reauth, client_missing and timeout. No tool opens a link.

Templates#

Kind api-key, by group:

• AI: openai, anthropic, google-gemini, mistral, groq, openrouter, together, ollama-cloud
• Code: github-pat, snyk, vercel, npm
• Work: linear, slack-bot, notion (send Notion-Version yourself), gitbook, fathom
• Observability: sentry, posthog, betterstack-uptime
• Infrastructure: cloudflare-api-token, hetzner-cloud, scaleway, neon
• Customers and email: stripe, hubspot-private-app, intercom, resend, postmark-server, loops
• Search and media: brave-search, serpapi, semrush, firecrawl, browserbase, elevenlabs, heygen

Kind oauth-client: google-oauth-client, github-oauth-client, microsoft-oauth-client. OAuth providers for mehen connect: google-gmail, google-calendar, google-drive, github-oauth, microsoft-graph.

mehen templates (MCP vault_templates) is the live list, grouped the same way, with what each allows, holds and refuses.

Setup for one agent#

mehen setup --json registers every agent it finds. To register only a named client, use its writer; inspect the report and restart that agent:

mehen setup --agent claude-code --json
mehen setup --agent codex --json
mehen setup --agent pi --json

--mcp-file <path> writes mcpServers.mehen into a compatible JSON client's file; use --agent vscode or --agent opencode for those clients' different formats. mehen setup --print --json prints the entry without writing anything.

AGENTS.md snippet#

Paste this into a repo's AGENTS.md (or CLAUDE.md) when the repo uses Mehen:

## Credentials

This repo uses Mehen. Secrets never appear in this repo, in chat or in your context.

- Never ask a human to paste a secret into chat, and never write one to a file, `.env` or commit.
  If one is pasted, do not use it; say it should be rotated.
- Run `mehen` with `--json`. Variables are declared in `mehen.toml` (committed, no values), which also
  names the project's workspace and vault. Check them with `mehen env check` and run anything that needs
  them with `mehen run -- <cmd>`. Read the `mehen:` line it prints on stderr and stop if the project or
  environment is wrong.
- Production runs need a literal `--env prod` and a human's approval. Never set `MEHEN_ENV=prod`.
- Call authenticated APIs with `mehen fetch <item> <METHOD> <url>` or the `vault_fetch` MCP tool.
  Never set auth headers or put a key or placeholder in a URL or body yourself.
- Missing credential: `mehen request <kind> --name <slug> --provider <template> --home project --reason "<why>"`
  (`--home project` puts it in this checkout's project, so the whole team can use it; without it the
  credential is private to the human), write the human the `ask` (link, what it is for, what to check,
  when it expires), then `mehen wait <id> --timeout 60 --json`. `mehen pending` lists the links still open. Trust only links under
  `https://app.mehen.dev/w/<slug>/` that `mehen` handed over.
- On any refusal, follow the `next` field and relay the `ask` or `next.say` to the human. Exit 3
  means approval required: send the link and the binding code, `mehen wait <approval> --timeout 60 --json`, then repeat
  the same request unchanged. Exit 5 means refused by rule: do not retry or work around it.
- Full guide: `mehen guide`.