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.
| Tool | Does | Blocks |
|---|---|---|
ask_human | Asks a question with options, typed fields or free text and waits. Returns outcome (answered, expired or timeout), answer and values | Yes |
request_approval | Asks 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 approval | Yes |
show_result | Posts a result for review: a local file (uploaded automatically), a folder or a URL. With review: true it waits for Looks good or Request changes | Only with review |
report_progress | Starts a live status card (title, optional steps) and updates it by card_id with value, label, step_done and status (running, succeeded, failed) | No |
note | Leaves a note to read later; no answer, no interruption | No |
set_metric | Writes a metric value (name, value, label, unit, better, goal) shown as a tile on your board | No |
update_board | Lists boards, patches one tile (board_id, tile_id, tile_patch) or replaces a board; needs a board key | No |
list_open_cards | Lists the cards still waiting for you, to avoid asking twice | No |
get_card | Reads one card and your response, optionally waiting wait_seconds for it to be answered | Optional |
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#
claude mcp add agentsframe -- npx -y agentsframe mcpThe 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:
{
"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:
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.
#!/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{
"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:
[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):
{
"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.