# Agent reference The parts of [the skill](https://docs.mehen.dev/skill.md) 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](https://docs.mehen.dev/reference/mcp.md), [providers and templates](https://docs.mehen.dev/reference/providers.md) and [the ask object](https://docs.mehen.dev/reference/ask.md). ## 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: ```sh mehen setup --agent claude-code --json mehen setup --agent codex --json mehen setup --agent pi --json ``` `--mcp-file ` 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: ```markdown ## 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 -- `. 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 ` 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 --name --provider