# Behavior Runtime MCP [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/putervision/behavior-mcp  
**GitHub Stars:** 8  
**npm Downloads (last month):** 3055  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/behavior-runtime-mcp

## Description
In-browser ~60Hz behavior tree execution engine with reactive triggers and safety guardrails.

## Tools
Capabilities this server exposes over MCP:

- **load_behavior** — Load, unload, or hot-swap a behavior tree instance in the browser runtime (actions: load, unload, swap). Use load_behavior instead of manage_behaviors when executing an active behavior tree instance at runtime rather than registering or inspecting definitions.

Returns execution handle, runtime state, active node, and session/intention bindings.
- **set_parameters** — Dynamically set, inspect, or reset execution parameters for the active behavior runtime (actions: set, get, reset). Use set_parameters instead of manage_blackboard for tuning tree-level execution variables and thresholds rather than sharing cross-node data keys.

Returns updated parameter map and execution ID.
- **get_status** — Query active behavior execution status, history, or full tree node traversal state (actions: current, history, tree_state). Use get_status instead of get_metrics when inspecting active execution state and node traversal paths rather than aggregated runtime performance telemetry.

Returns execution status, current node path, tick counters, duration, and error states.
- **abort_behavior** — Immediately halt, pause, resume, or unstick behavior execution and disengage active inputs (actions: abort, pause, resume, unstick). Use abort_behavior instead of register_trigger when manually halting or recovering execution rather than configuring automatic condition interrupts.

Returns transition status, disengaged inputs, and unstick diagnostics.
- **register_trigger** — Configure or list reactive interrupt triggers with priority preemption and cooldown guards (actions: register, list). Use register_trigger instead of abort_behavior when defining automatic condition-based interrupts rather than manually pausing or stopping a tree.

Returns registered trigger configuration, ID, or trigger list.
- **replay_recording** — Capture or list deterministic browser action sequences with adaptive timing (actions: capture, list). Use replay_recording instead of load_behavior when recording or inspecting fixed action sequences rather than running a dynamic behavior tree.

Returns recording metadata, frame sequences, or list of stored recordings.
- **get_metrics** — Retrieve runtime execution telemetry, tick durations, stuck events, category statistics, and 60Hz action outcome spool entries (actions: current, history, aggregate, compare, spool, drain_spool). Use get_metrics instead of get_status when evaluating tick performance, reading spooled action outcomes, or inspecting aggregated statistics rather than active node traversal.

Returns telemetry metrics, duration percentiles, stuck event counts, spooled outcome records, or drained entry counts.
- **manage_behaviors** — Manage immutable JSON behavior tree definitions with SHA-256 hash verification (actions: register, list, get, synthesize). Use manage_behaviors instead of load_behavior when defining, versioning, or synthesizing behavior tree structures rather than executing them.

Returns tree definition, version metadata, SHA-256 content hash, or synthesis DAG.
- **manage_blackboard** — Read, write, delete, lease, list, or ingest structured state slices into shared behavior tree blackboard state (actions: get, set, delete, lease, list, ingest_slice). Use manage_blackboard instead of set_parameters when coordinating state across behavior nodes, projecting perception/spatial slices with staleness protection, or acquiring agent mutex leases.

Returns blackboard value, lease acquisition status, key listings, or slice ingestion summary with expiry metadata.
- **manage_runtime_db** — Database maintenance, diagnostics, SHA-256 Merkle audit verification, and snapshot management (actions: stats, audit, doctor, snapshot, diff, restore). Use manage_runtime_db instead of get_metrics when auditing SQLite integrity and Merkle proofs or restoring database snapshots.

Returns maintenance diagnostics, Merkle audit trees, snapshot metadata, or diff reports.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "behavior-runtime-mcp": {
    "command": "npx",
    "args": ["-y","@putervision/behavior-mcp"],
    "env": {
      "PENTAD_HMAC_SECRET": ""
    }
  }
}
```

**Requires environment variables:** `PENTAD_HMAC_SECRET` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Behavior Runtime MCP MCP server does

Behavior Runtime MCP MCP server connects an MCP client to a browser-based behavior-tree runtime. It executes immutable behavior-tree JSON definitions on a roughly 60Hz loop and supports reactive triggers that can preempt active behavior according to priority. Runtime state includes execution status, node traversal, tick counts, durations, blackboard values, trigger registrations, metrics, recordings, and audit information.

The server is intended for agent-controlled tactical or procedural behavior where execution needs explicit controls and inspection. Behaviors can be loaded, unloaded, or hot-swapped while runtime parameters and shared blackboard values can be queried or changed. Execution can also be aborted, paused, and resumed.

## How it works

Behavior Runtime MCP MCP server exposes ten grouped MCP tools. Behavior definitions are registered and retrieved through `manage_behaviors`, which stores immutable JSON and SHA-256 tree hashes. `load_behavior` controls which tree is active, while `get_status` reports the current or historical execution state and tree traversal path.

Reactive interruptions are configured with `register_trigger`. `replay_recording` captures or lists deterministic browser action sequences, and `get_metrics` reports tick timing, telemetry, history, and stuck events. The shared blackboard is managed separately through `manage_blackboard`.

Runtime persistence and recovery are handled by `manage_runtime_db`, including SQLite statistics, audit inspection, snapshots, and restore operations. Audit data uses SHA-256 Merkle chains. The execution loop is designed not to wait on external network calls; semantic checks resolve synchronously against blackboard caches.

## Setup and configuration

The package requires Node.js 20 or newer. Initialize a workspace and seed its default behavior trees with:

```bash
npx @putervision/behavior-mcp init
```

Run diagnostics with `npx @putervision/behavior-mcp doctor`, inspect active executions with `npx @putervision/behavior-mcp inspect`, and start the MCP server with `npx @putervision/behavior-mcp run`.

For MCP client configuration, use the `behavior-mcp` server name, the `behavior-mcp` command, and the `run` argument. Set `PENTAD_HMAC_SECRET` to the shared secret used to verify signed intention dispatch tokens. Configuration can also be defined through `.behavior-mcp.json`; the repository provides a separate configuration reference for available settings.

## Tools and capabilities

The ten tool groups provide these operations:

- Load, unload, or swap behavior trees.
- Set, retrieve, or reset runtime parameters.
- Query current status, execution history, and tree state.
- Abort, pause, or resume behavior execution.
- Register and list priority-based reactive triggers.
- Capture and list browser action recordings.
- Read current and historical runtime metrics.
- Register, retrieve, and list behavior definitions.
- Read and write blackboard variables.
- Inspect SQLite data, audit records, snapshots, and restores.

## Limitations and notes

Behavior Runtime MCP MCP server applies a fail-closed evaluator: unknown node definitions produce fatal exceptions. Its tick invariant targets approximately 60Hz, and its action rate limit caps throughput at 60 actions per second. Leaf policy controls can block irreversible mutations.

The safety stack also requires valid, unexpired HMAC-signed dispatch tokens, and a watchdog can stop execution when a tick stalls for more than 5,000 milliseconds. An emergency kill switch provides an additional execution halt. These controls mean behavior definitions and dispatch configuration must conform to the runtime’s validation and safety rules.

The repository documents a five-layer guardrail design, SQLite schema, CLI usage, API schemas, and configuration details. It does not describe support for behavior-tree formats other than its JSON definitions or provide client-specific setup beyond the standard MCP command configuration.

_Full upstream README: https://allmcps.com/mcp/behavior-runtime-mcp/readme_