Skill: leiarenee/agentmfa (version 1.0.14)

--- name: agentmfa description: AgentMFA — request human approval before sensitive actions. Uses MCP tools for registration, identity, and approval flows. Works in Claude Code, Cursor, OpenClaw, and any MCP-compatible client. homepage: https://agentmfa.ai license: MIT metadata: openclaw: emoji: "🔐" requires: bins: - agentmfa install: - id: brew kind: shell command: "brew install agentmfa/cli/agentmfa && agentmfa auth login" label: "Install AgentMFA CLI and log in" --- # AgentMFA Skill **AgentMFA is an opt-in approval system.** The agent must explicitly call these tools before sensitive actions. AgentMFA does not automatically intercept or block anything — the agent decides when to request approval. When the agent calls `request_approval`, the human operator receives a push notification, reviews the action, and approves or rejects it with biometrics. The agent then decides whether to proceed based on the response. ## Subcommands These are CLI-only operations, run via Bash: | Invocation | Action | |---|---| | `/agentmfa list` | Run `agentmfa agent list` and display the results. | | `/agentmfa status` | Run `agentmfa auth status` to show login state. | --- ## About AgentMFA - **Operator:** AgentMFA (https://agentmfa.ai) - **MCP server:** `agentmfa serve` — part of the AgentMFA CLI; stdio MCP on your machine, talking to `api.agentmfa.ai` - **Auth:** OAuth via `agentmfa auth login` (session in the system keychain) - **Privacy & security policy:** https://agentmfa.ai/privacy - **Source code:** https://github.com/agentmfa/agentmfa (fully open source) The `agentmfa` CLI must be installed and logged in before this skill can be used. ## Setup ```sh # 1. Install the CLI brew install agentmfa/cli/agentmfa # 2. Log in (opens browser for OAuth) agentmfa auth login ``` Registration happens automatically via the `register_agent` MCP tool — no manual step needed. ## When to Use The agent should call AgentMFA tools before: - Deleting or modifying production data - Deploying code to production - Sending emails or messages on behalf of the user - Actions that could result in financial charges or transactions - Modifying infrastructure (cloud resources, DNS, etc.) - Any action the agent recognizes as sensitive or irreversible **Common risky actions requiring approval:** - `git push --force` or rewriting history - `kubectl delete` on production resources - `kubectl apply/edit` to running workloads - `terraform apply` (especially with deletions shown in plan) - `terraform destroy` on any environment - `rm -rf` or bulk file deletions - Database schema changes or deletions - Modifying secrets (SOPS encrypt/decrypt) - Force pushing branches (`git push -f`) - Checking out or switching branches in production repos **Note:** AgentMFA does not automatically detect sensitive actions. The agent must recognize the risk and explicitly invoke the approval flow. ## How to Use This skill uses the AgentMFA MCP tools exposed by **`agentmfa serve`**. Your agent uses **only MCP tool calls** — no direct HTTP. Tool parameter names must match the MCP schema your client shows (see table below). Put the **short label** in `action` and **full detail** in `context` so the operator sees enough to decide. ### Standard flow ``` 1. Call register_agent() → Checks if already registered — returns immediately if so → If not registered, registers and waits for approval (auto or mobile) → Returns: { status, tool, remote, message } ⚠️ Relay the message to the user 2. Call request_approval(action, description, context?) → Returns: { request_id, message } ⚠️ Relay the message so the user knows to check their phone 3. Call wait_for_approval(request_id) → Blocks until decided (polls every 1s, default 300s timeout) → Approved: { approved: true, totp_verified, token, agent_totp, server_time, approved_by, approved_from, message } → Rejected: { approved: false, reason } ⚠️ On approval, relay the message field verbatim 4a. approved == true → proceed 4b. approved == false → abort and inform the user ``` ### Identity check Call `agent_info()` to see the locally detected identity — tool name, repository, branch, machine, code signature, verification mode, and registration status. Useful for debugging. ### Non-blocking check Use `check_approval_status(request_id)` to poll once without blocking. ## Rules - **The agent decides when to call AgentMFA** — nothing forces automatic approval checks - **Always wait** for approval before proceeding — never skip or assume approval - **Abort on rejection** — do not retry the same action without user re-initiation - **Abort on expiry** — a timed-out request is treated as rejected - **Be specific** — `action` and `context` should give the human enough detail to decide - **Handle tokens carefully** — one-time proofs of approval should not be logged or pasted into chat ## MCP Tools | Tool | Parameters | Purpose | |---|---|---| | `agent_info` | _(none)_ | Local identity data — tool, repo, branch, machine, signature, registration status | | `register_agent` | `role` (optional), `force` (optional boolean) | Register this agent. Checks first, blocks until decided | | `request_approval` | `action` (required), `description` (required), `context` (optional), `services` (optional array) | Submit approval request; returns `request_id` + `message` | | `wait_for_approval` | `request_id` (required), `timeout` (optional, default 300s) | Block until decided | | `check_approval_status` | `request_id` (required) | Single non-blocking poll | ### OpenClaw Users In OpenClaw, MCP tools are namespaced with the server name prefix. Use these exact tool names: - `agentmfa__agent_info` - `agentmfa__register_agent` - `agentmfa__request_approval` - `agentmfa__wait_for_approval` - `agentmfa__check_approval_status`

path: _meta.json
content: ownerId: kn7649qhpdar9qk5q42dx6k2698537f1
slug: agentmfa
version: 1.0.13
publishedAt: 1776549820437

path: references/errors.md
content: # AgentMFA Error Handling

## Tool call outcomes

| Status | Meaning | Action |
|--------|---------|--------|
| `approved` | Human approved with biometrics | Proceed; log the `code` as proof |
| `rejected` | Human rejected | Abort the action; inform the user |
| `expired` | Request timed out | Abort; treat as rejected |

## Rules

- Never proceed without `"status": "approved"`
- Never retry a rejected request automatically — only the human can re-initiate
- Never reuse a `code` — each approval generates a unique one-time approval code


path: references/examples.md
content: # AgentMFA MCP Examples

These examples show how an agent (Claude Code, Cursor, or any client running `agentmfa serve`) should use the AgentMFA MCP tools. No HTTP calls, no environment variables — just tool calls. Parameter names match the `agentmfa serve` stdio server.

---

## Basic approval before a destructive action

```
// Step 1 — request approval (short label in action, detail in context)
request_approval(
  action: "Delete S3 bucket prod-data",
  context: "2.3GB of production backups from 2024; irreversible",
  risk_level: "high"
)
// → JSON with id (use as request_id), e.g. { "id": "abc-123", "status": "pending", ... }

// ⚠️  Tell the user: "Request sent — waiting for your approval on the phone..."

// Step 2 — wait for human decision
wait_for_approval(request_id: "abc-123")
// → JSON when status is no longer pending (fields depend on API), e.g.:
//   { "status": "approved", "code": "..." }  or similar
// → or timeout: { "status": "expired", "message": "..." }  — treat as rejected

// Step 3 — act on result
if approved / success  → relay any human-facing message, then proceed
if rejected / expired  → abort, tell user the action was not approved
```

---

## With custom timeout

```
wait_for_approval(
  request_id: "abc-123",
  timeout_seconds: 120   // default is 300; server polls about every 3s
)
```

---

## Non-blocking (manual polling)

```
// Request
request_approval(
  action: "Send invoice emails",
  context: "247 recipients; batch job"
)
// → use "id" from the response as request_id

// Do other preparation work here...

// Check when ready
check_approval_status(request_id: "xyz-456")
// → { "status": "pending" }   ← still waiting
// → { "status": "approved", "code": "..." }  ← done (exact fields from API)
```

---

## Risk levels

| risk_level | When to use |
|---|---|
| `low` | Reversible actions, small blast radius |
| `medium` | Default — partially reversible or moderate impact |
| `high` | Irreversible, large blast radius, or financial impact |


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)