Skip to content

MCP tool reference

Auto-generated by scanning crates/mcp/src/tools.rs. Run scripts/docs/regen.py to refresh.

AppControl ships an MCP (Model Context Protocol) server that exposes the production stack to any MCP-compatible client: Claude Desktop, Claude Code, Cursor, ChatGPT (via bridge), and others. The MCP server is a thin shim — every tool call resolves to one REST API call, with the same auth and audit semantics as a CLI or UI call. Every MCP-triggered action lands in action_log with actor_type='mcp'.

Setup

// ~/.config/claude-desktop/claude_desktop_config.json
{
  "mcpServers": {
    "appcontrol": {
      "command": "appcontrol-mcp",
      "args": ["--url", "https://appcontrol.example.com"],
      "env": {
        "APPCONTROL_API_KEY": "ac_xxxxxxxxxxxx"
      }
    }
  }
}

The MCP binary is shipped alongside the backend; run appcontrol-mcp --help for the version-specific flags.

Tools

21 tools exposed.

Tool Required args Description
get_application_knowledge (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
propose_application_map (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
list_apps (none) List every application the API key can see.
get_app_status app_name Return current overall status, per-component states, and the FSM transition history for an application.
start_app app_name, dry_run Start an application in DAG order. Pass dry_run=true to validate the plan without dispatching.
stop_app app_name Stop an application in reverse-DAG order.
diagnose_app app_name Run the 3-level diagnostic (Health / Integrity / Infrastructure) and return the recommendation matrix.
rebuild_app (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
get_rebuild_status (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
get_incidents app_name, days Return incidents (FSM transitions to FAILED) over the last days days. Default: 7 days.
get_topology app_name Return the DAG: nodes, edges (strong/weak), groups, and per-component metadata.
estimate_time app_name, operation Estimate how long operation (start or stop) will take based on historical execution times for this application.
get_activity app_name, limit Return the most recent rows from action_log for this application, capped by limit (default 20).
list_agents (none) List enrolled agents with hostname, last heartbeat, and version.
list_log_sources app_name, component_name List the log streams an agent exposes for a given component (declared in log_sources on the component).
get_component_logs app_name, component_name, source, lines Tail the last N lines from a component log stream. Useful for claude code-driven incident analysis.
run_diagnostic_command (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
search_logs (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
file (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
event_log (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)
command (none) (undocumented — add to scripts/docs/gen_mcp.py::TOOL_DESC)

Permissions and audit

MCP requests authenticate with the same API keys as the CLI and REST API:

  • The key carries the user's effective permission. start_app on an application where the key has only View returns the same forbidden error as the REST endpoint would.
  • Every tool call is recorded in action_log with actor_type='mcp' and the tool name in action_log.action. Audit reports surface MCP-triggered actions identically to UI-triggered ones.
  • Read-only tools (list_apps, get_app_status, …) still appear in the audit trail — DORA Article 16 requires every access to be loggable, not just mutations.

Example session (Claude Desktop)

User:  Which components of core-banking failed in the last 24h?
Claude: [calls get_incidents(app_name='core-banking', days=1)]
       Two components transitioned to FAILED in the last 24h:
       — batch-eod (07:14 UTC, exit_code=2)
       — settlement-queue (11:02 UTC, exit_code=1, recovered at 11:08)

User:  Show me the last 40 lines of batch-eod's stderr.
Claude: [calls get_component_logs(app_name='core-banking', component_name='batch-eod', source='stderr', lines=40)]