# Behavior Runtime MCP server

> Executes deterministic behavior trees in browser runtimes at 60Hz with reactive triggers and blackboard state management.

- Repository: https://github.com/putervision/behavior-mcp
- Page: https://hostedmcp.org/servers/putervision/behavior-mcp
- Transport: stdio
- Stars: 8
- License: MIT
- Latest version: 0.4.1

## Install

### Claude Code

```sh
claude mcp add behavior-mcp -- npx -y @putervision/behavior-mcp
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "behavior-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@putervision/behavior-mcp"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"behavior-mcp","type":"stdio","command":"npx","args":["-y","@putervision/behavior-mcp"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add behavior-mcp -- npx -y @putervision/behavior-mcp
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.behavior-mcp]
command = "npx"
args = ["-y", "@putervision/behavior-mcp"]
```

### Gemini CLI

```sh
gemini mcp add -s user behavior-mcp npx -- -y @putervision/behavior-mcp
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `PENTAD_HMAC_SECRET` | no | no |  |

## Tools (10)

- `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. (read-only)
- `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. (read-only)
- `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.

## FAQ

### How can I initialize the runtime and seed default behavior trees?

You can initialize the runtime and seed default behavior trees in your workspace using the command 'npx @putervision/behavior-mcp init'.

### Does the execution loop block on network calls?

No, the 60Hz tick invariant ensures the loop never blocks on external network calls, resolving semantic checks synchronously against blackboard caches.
