MCP setup#

The Frame MCP server gives any MCP-capable agent five tools to reach you. It runs locally over stdio and talks to the API with your key.

Tools#

The server exposes nine tools. The two that ask a question block until you answer; the rest return at once.

ToolDoesBlocks
ask_humanAsks a question with options, typed fields or free text and waits. Returns outcome (answered, expired or timeout), answer and valuesYes
request_approvalAsks you to approve or deny an action before the agent takes it (custom actions allowed). Returns approved, the chosen action and your comment. Expired or timed out means no approvalYes
show_resultPosts a result for review: a local file (uploaded automatically), a folder or a URL. With review: true it waits for Looks good or Request changesOnly with review
report_progressStarts a live status card (title, optional steps) and updates it by card_id with value, label, step_done and status (running, succeeded, failed)No
noteLeaves a note to read later; no answer, no interruptionNo
set_metricWrites a metric value (name, value, label, unit, better, goal) shown as a tile on your boardNo
update_boardLists boards, patches one tile (board_id, tile_id, tile_patch) or replaces a board; needs a board keyNo
list_open_cardsLists the cards still waiting for you, to avoid asking twiceNo
get_cardReads one card and your response, optionally waiting wait_seconds for it to be answeredOptional

The blocking tools wait up to timeout_seconds (default 600). On timeout the card stays open and the tool says so, so the agent can decide what to do, or collect the answer later with get_card. Use a write key for everything except update_board, which needs a board key.

Claude Code#

bash
claude mcp add agentsframe -- npx -y agentsframe mcp

The server reads the same configuration as the CLI: run npx agentsframe login --key afk_w_… once, or pass the key as an environment variable with --env AGENTSFRAME_KEY=afk_w_… before the --. You can also run the dedicated binary: claude mcp add agentsframe -- npx -y -p agentsframe agentsframe-mcp.

Or put it in .mcp.json at the project root:

.mcp.json
{
  "mcpServers": {
    "agentsframe": {
      "command": "npx",
      "args": ["-y", "agentsframe", "mcp"],
      "env": { "AGENTSFRAME_KEY": "afk_w_xxxxxxxx" }
    }
  }
}

Tell the agent when to use it, for example in CLAUDE.md:

CLAUDE.md
When you need a decision that is risky or irreversible (deploying, deleting, spending money),
call `request_approval` and wait. When you finish a long task, call `show_result`.

Approve risky tool calls#

A PreToolUse hook can turn permission prompts for dangerous commands into approval cards. Exit code 2 blocks the tool call and shows stderr to the agent.

~/.claude/hooks/frame-gate.sh
#!/usr/bin/env bash
# Reads the hook JSON on stdin, asks you on your phone, blocks when not approved.
CMD=$(jq -r '.tool_input.command // empty')
[ -z "$CMD" ] && exit 0
if frame approve "Run: ${CMD:0:100}" --class claude.bash --timeout 300 --on-expire deny >/dev/null; then
  exit 0
fi
echo "The owner did not approve this command." >&2
exit 2
settings.json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "~/.claude/hooks/frame-gate.sh" }] }
    ]
  }
}

Pair it with a rule that auto-approves the class claude.bash.safe if you want only the risky ones to ring.

Codex#

Add the server to ~/.codex/config.toml:

~/.codex/config.toml
[mcp_servers.agentsframe]
command = "npx"
args = ["-y", "agentsframe", "mcp"]
env = { AGENTSFRAME_KEY = "afk_w_xxxxxxxx" }

Or with the CLI: codex mcp add agentsframe --env AGENTSFRAME_KEY=afk_w_xxxxxxxx -- npx -y agentsframe mcp. If you have run frame login, the env line is optional.

Cursor#

Add to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

mcp.json
{
  "mcpServers": {
    "agentsframe": {
      "command": "npx",
      "args": ["-y", "agentsframe", "mcp"],
      "env": { "AGENTSFRAME_KEY": "afk_w_xxxxxxxx" }
    }
  }
}

Any other client#

The server speaks MCP over stdio: start npx -y agentsframe mcp with AGENTSFRAME_KEY (and optionally AGENTSFRAME_API) in the environment. If your client can read a key from the environment you do not need to write it into a config file.

Troubleshooting#

Run frame doctor in the same environment first: it checks the key, the scope and whether a device can receive pushes. If a tool reports plan_required or quota_exceeded the error is passed through with its hint, so the agent can tell you what to do.