a360-mcp

MCP server for Automation Anywhere Automation 360 (A360) Control Room — bot logic analysis and execution failure diagnostics.

Community project. Not affiliated with or endorsed by Automation Anywhere, Inc. "Automation Anywhere" and "Automation 360" are trademarks of their respective owner.

What it is for

A bot ran. It died. Which action, why, and what was missing upstream?

This server pulls the failed execution from the Control Room, pulls the bot's logic, and maps one onto the other — so the answer is "action 37, Open Excel, file not found; there is no existence check before it and no error handler around it" rather than a status code.

What it is not

Automation Anywhere ships MCP Inbound (https://<control-room>/mcp) from v.38, which exposes bots as tools so an assistant can run them. If running bots is what you need, use the vendor feature — it has RBAC, governance logging, and per-automation registration.

It does not read execution history, bot logic, WLM queues, or audit logs. That is this project's scope. The two are complementary.

Status

Beta. Diagnostic pipeline (diagnose_execution), bot logic walker, and snapshot store are implemented and unit-tested (647 tests). Writes are opt-in and gated. Not yet validated against a live Control Room instance — the A360 filter operator set and bot JSON node schema are permissive parsers, awaiting field verification.

Requirements

• Python 3.11+
• An Automation 360 Control Room account with an API key (needs a custom role carrying Generate API-Key — no system role has it by default)
• Read privileges on the bots you want to diagnose (View my bots)

Setup

The default is uvx — no separate install step, it just runs.

# Install uv (one-time)
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Verify the server runs
uvx --from a360-mcp a360-mcp --version

To update — uvx caches the last version; pull new releases with --refresh:

uvx --refresh --from a360-mcp a360-mcp --version

If uvx is blocked — pip

Windows Smart App Control blocks uvx (it unpacks an unsigned temporary executable on every run). Use pip instead:

pip install a360-mcp
python -m a360_mcp --version

Launch with python -m a360_mcp rather than the a360-mcp console script — that script is an unsigned .exe shim pip generates, and SAC blocks it too.

MCP client configuration

Add the server to your client's config file. The env block is identical no matter how you installed — only command / args differ.

Required env vars:

Claude Code

.mcp.json (project root) or ~/.claude.json (global):

{
  "mcpServers": {
    "a360": {
      "command": "uvx",
      "args": ["--from", "a360-mcp", "a360-mcp"],
      "env": {
        "A360_CONTROL_ROOM_URL": "https://cr.example.com",
        "A360_USERNAME": "svc_mcp",
        "A360_API_KEY": "${A360_API_KEY}"
      }
    }
  }
}

Codex

.codex/config.toml (project) or ~/.codex/config.toml (global):

[mcp_servers.a360]
command = "uvx"
args = ["--from", "a360-mcp", "a360-mcp"]
# pip: command = "python"  /  args = ["-m", "a360_mcp"]

[mcp_servers.a360.env]
A360_CONTROL_ROOM_URL = "https://cr.example.com"
A360_USERNAME = "svc_mcp"
A360_API_KEY = "${A360_API_KEY}"

OpenCode

opencode.json (project root):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "a360": {
      "type": "local",
      "command": ["uvx", "--from", "a360-mcp", "a360-mcp"],
      "enabled": true,
      "environment": {
        "A360_CONTROL_ROOM_URL": "https://cr.example.com",
        "A360_USERNAME": "svc_mcp",
        "A360_API_KEY": "${A360_API_KEY}"
      }
    }
  }
}

${ENV} reference

The CLI expands ${VAR} as a full value only — A360_API_KEY=${A360_API_KEY} resolves to the value of the A360_API_KEY env var at startup. Partial references like ${ENV}_suffix are rejected to prevent silent misconfiguration.

Tools

The server exposes a layered tool set, gated by A360_TOOL_PACKAGE (default core):

Set with A360_TOOL_PACKAGE=diagnose (env) or --tool-package diagnose (CLI).

Headline tool: diagnose_execution

Given an execution ID, returns a verdict-first diagnosis:

1. Fetch the execution (GET /v3/activity/execution/{id}).
2. If the status is not failure-family, return a one-line verdict immediately.
3. Feature-detect the error key, fall back to parsing message.
4. Fetch the bot logic (GET /v2/repository/files/{fileId}/content).
5. Walk action nodes (iterative DFS, no recursion).
6. Map the failure onto a node by line number.
7. Pull upstream / downstream context and Try/Catch presence.
8. If no Try/Catch, emit an instrumentation prescription ("place Catch with line number + exception message assignments, log to server, screen capture inside").
9. Snapshot the diagnosis locally (90-day CR retention fallback).

Bot JSON never enters the model context — only the parsed action surface and a disk path.

Authentication

The server uses POST /v2/authentication with the X-Authorization: <token> header (no Bearer prefix). Tokens live 20 minutes; refreshes are serialized under a mutex because refresh kills the previous token. An account may hold only 5 concurrent sessions — the token is cached and the optional debug browser window consumes one slot too.

API key is preferred for service accounts; password is supported but should be paired with a non-2FA role (the A360 v2 auth request has no mfaCode field).

Safety

• Writes are opt-in per instance — allow_writes defaults to False. A missing flag never means "writable".
• Mutating tools (deploy / publish / update / delete / create / cancel / stop / upload / rename / move / checkout / checkin, plus the browser window tools) require approve=true in the tool call.
• Publish-grade tools (deploy / publish) require an additional confirm_environment=prod field, so a single confirmation cannot ship to production.
• The browser layer never clicks. It observes console, network, screenshots, and computed CSS. inspect_* tools structurally cannot open a window — only open_debug_window can.
• Fail-open by default for write guards; flip with A360_WRITE_GUARDS_FAIL=closed.
• Diagnosed executions are snapshotted locally on first read — the 90-day cloud retention limit has no backup path otherwise.

Every refusal states the next action. Never refuses without a path forward.

Cloud retention

Diagnosed executions are cached under state_dir()/snapshots/{account_key}/ with the bot logic at time of diagnosis. Re-diagnosing an old execution reads from disk, not the Control Room, and the response is marked original_expired past 90 days.

Developer setup

git clone https://github.com/jshsakura/a360-mcp.git
cd a360-mcp
uv venv --python 3.12 .venv
uv pip install -e ".[dev]"

# Tests — always run pytest under the memory-cap wrapper, raw pytest has
# killed the local tmux session before.
saferun -m 4G .venv/bin/pytest tests/ -q

# Lint / format / type
.venv/bin/ruff check src tests
.venv/bin/black src tests
.venv/bin/isort src tests
.venv/bin/mypy src

Browser tests are mocked (Playwright is a soft dependency, lazy-imported). To exercise the real browser layer:

uv pip install -e ".[browser]"
playwright install chromium

License

Apache-2.0. See LICENSE.