MCP Server

ActionBox provides a hosted MCP server at https://api.actionbox.cloud/mcp. The public CLI exposes it through a local stdio bridge, so an MCP host can use ActionBox's human-input tools without placing a Source key in JSON-RPC messages or chat history.

Install and configure

Install the public CLI from PyPI, create a Source in the dashboard, then store the Source credential in the CLI's protected local configuration:

python -m pip install actionbox
actionbox configure
actionbox doctor

Add ActionBox to an MCP host

Use actionbox mcp as the local stdio command:

{
  "mcpServers": {
    "actionbox": {
      "command": "actionbox",
      "args": ["mcp"]
    }
  }
}

The bridge forwards MCP messages to the hosted ActionBox service. A human reviews the Action in the hosted web inbox, and the MCP host receives the durable typed result after the Action is resolved.

For a step-by-step reviewer decision and guidance on where to enforce the downstream tool boundary, read MCP human-in-the-loop.

Exact tool inventory

The hosted server exposes exactly six tools. Every tool is scoped to the authenticated Source; it cannot read or change another Source's Actions.

Tool	Capability	Permission semantics
`ask_human`	Create a durable Action	Write; the human answer still occurs in the hosted inbox
`get_action`	Read one Action, optionally waiting briefly	Read-only
`list_actions`	List the Source's own Actions	Read-only
`update_action`	Update an open Action with newer bounded context	Write; cannot update a terminal Action
`cancel_action`	Cancel an open Action that is no longer relevant	Destructive terminal transition attributed to the Source
`resolve_action`	Record a machine-selected response	Destructive terminal transition attributed to the Source; never a human approval

ask_human accepts either assignee_email or assignee_user_id when an Action must go to one active reviewer. Both are optional; send at most one. Copy the stable ID from Settings → Team, or omit assignment to use the workspace default and normal plan routing.

For a Team-only restricted Action, set private to true and pass one list: reviewer_emails or reviewer_user_ids. Lists accept up to 15 active reviewers. Only named reviewers can claim or decide it; workspace owners and admins retain management visibility.

ask_human also accepts a typed approval_policy for Team-only any, all, or quorum review. Human votes still happen in the hosted web or mobile inbox. resolve_action can send approval_override: true only when the immutable policy allowed it and the Source supplies a reason plus the current version and fingerprint. See Approval Policies.

Follow-up information

MCP ask_human defaults context_request_mode to poll. This tells the reviewer UI that the agent can receive a follow-up question through get_action, then answer it with update_action. A static script that cannot provide more information should set the mode to unsupported. callback is available when the Source supplies a callback_url and handles action.context_requested events.

A pending request remains visible until the Source provides context or reports that it is unavailable. A deduplicated update cannot hide the request merely by changing the capability mode.

resolve_action exists for cases where the underlying condition is handled or becomes moot. It must not be used to approve the agent's own work or impersonate a reviewer. Enforced approval around another MCP server still belongs in the application or gateway that controls that downstream tool call.

Browser WebMCP

WebMCP is a browser API, separate from the hosted MCP server above. On the hosted actionbox.cloud app, a signed-in reviewer using a browser that exposes the draft WebMCP API can let an agent list or open visible Actions and request more context.

The actionbox_submit_decision browser tool only prepares a response and opens an ActionBox confirmation. It does not resolve the Action. ActionBox rechecks the reviewer role, Action version, fingerprint, and response when the reviewer deliberately clicks Confirm decision. Confirmed events remain human-attributed and record resolved_via: WEBMCP in the audit payload.

Security boundary

Run actionbox configure locally; never paste a raw axb_live_… key into a prompt, chat, MCP configuration, log, command argument, or repository.
Treat the Action state returned by ActionBox as authoritative. A local client timeout does not approve or resolve an Action.
Keep each MCP JSON-RPC request at or below 256KB. Larger request bodies are rejected before parsing with HTTP 413 ACTION_PAYLOAD_TOO_LARGE.
Use a separate Source for each independent agent or automation boundary so credentials can be rotated or revoked without affecting unrelated callers.
Run actionbox doctor after configuration changes to verify the hosted API connection without displaying the Source key.

Run actionbox mcp --help for the exact behavior shipped with the installed CLI version. See Sources and keys for credential lifecycle and Decisions and outcomes for terminal Action state.