Open-source Revit MCP server: let Claude and other AI assistants read and edit BIM models, with human approval on every change.
ADR 0008: Approval Gate & ActionPlan Lifecycle
Status
Accepted. Status: on the dev branch, not yet released. Nothing here has run in a live Revit session (UNVERIFIED).
Context
AI agents modifying production BIM models (e.g., Revit, Navisworks) pose significant risks of silent data corruption, coordinate drift, or breaking company standards. We need a secure boundary where AI agents can propose changes (read, analyze, and plan) but can never execute modifying operations directly without explicit human review and approval.
Decisions
1. ActionPlan Lifecycle
An ActionPlan is the unit of human approval and execution control. It transitions through the following states:
---
config:
look: neo
theme: base
themeVariables:
primaryColor: "#334155"
primaryTextColor: "#FFFFFF"
primaryBorderColor: "#1E293B"
secondaryColor: "#334155"
tertiaryColor: "#334155"
lineColor: "#6E7781"
textColor: "#6E7781"
titleColor: "#6E7781"
nodeTextColor: "#FFFFFF"
clusterBkg: "rgba(110,119,129,0.10)"
clusterBorder: "#6E7781"
edgeLabelBackground: "#334155"
actorBkg: "#334155"
actorTextColor: "#FFFFFF"
actorBorder: "#1E293B"
actorLineColor: "#6E7781"
signalColor: "#6E7781"
signalTextColor: "#6E7781"
labelBoxBkgColor: "#334155"
labelBoxBorderColor: "#6E7781"
labelTextColor: "#FFFFFF"
loopTextColor: "#6E7781"
sequenceNumberColor: "#FFFFFF"
noteBkgColor: "#F59E0B"
noteTextColor: "#1F1300"
noteBorderColor: "#92400E"
transitionColor: "#6E7781"
transitionLabelColor: "#FFFFFF"
stateLabelColor: "#FFFFFF"
stateBkg: "#334155"
labelBackgroundColor: "#334155"
compositeBackground: "#334155"
specialStateColor: "#6E7781"
---
stateDiagram-v2
state "Pending review" as Pending
state "Rolled back" as RolledBack
[*] --> Draft
Draft --> Validated: plan_actions
Validated --> Pending: submit
Pending --> Approved: approve
Pending --> Rejected: reject
Approved --> Executed: execute
Executed --> RolledBack: rollback_plan
Rejected --> [*]
RolledBack --> [*]
classDef ok fill:#0F766E,stroke:#0B4F4A,color:#FFFFFF
classDef blocked fill:#B91C1C,stroke:#7F1D1D,color:#FFFFFF
class Approved,Executed ok
class Rejected blocked
- Draft: A plan containing proposed actions (tool calls and arguments) under construction.
- Validated: The plan has been checked against schemas, and dry-run validation checks have run (e.g., uniqueness, category support, element ownership).
- Pending: Submitted to the human approval queue, visible on the dockable panel.
- Approved: Human checked the parameter diffs and element counts, giving explicit consent.
- Rejected: Human rejected the plan; it is closed and archived.
- Executed: The changes are applied to the model inside host transactions.
- Rolled Back: The recorded changes are reversed by
rollback_plan, which applies inverse parameter values and can skip an action that has no recorded before-value.rollback_planis for people only and has no panel button oraec-model-bridge-approvecommand yet. Revit's own Ctrl+Z, or a revert plan drafted withplan_revertand approved like any other plan, are the practical routes. None is verified in a live Revit session (UNVERIFIED).
2. ActionPlan Schema
The ActionPlan represents a batch of modifications:
{
"plan_id": "plan_01J...ULID",
"state": "pending",
"created_at": "2026-07-08T18:07:30Z",
"actions": [
{
"action_id": "act_01...",
"tool": "revit.batch_set_parameters",
"arguments": {
"elements": ["revit-uniqueid-1"],
"parameter": "FireRating",
"value": "60"
},
"diff": {
"type": "parameter_change",
"before": {"revit-uniqueid-1": {"FireRating": null}},
"after": {"revit-uniqueid-1": {"FireRating": "60"}},
"element_count": 1
}
}
],
"is_reversible": true,
"reversible_strategy": "inverse"
}
3. The Approval Gate Middleware
- Enforcement Location: The unified Python MCP hub acts as the single choke point.
- Rule: If
approval_modeisask_first(the default;requiredis the older name for the same mode), any tool call containing mutating or destructive metadata (is_mutating=Trueordestructive=True) must supply a valid, approvedplan_id. Unplanned mutations are immediately blocked and returned as an authorization error. - Bound to the approved action (approval v2): a call with a
plan_idmust match a not-yet-run action of that plan by tool name and canonical arguments (plan_id,run_async,idempotency_keyare ignored; key order and5vs5.0do not matter). Only apendingplan can be approved; apendingorapprovedplan can be rejected, so a person can withdraw an approval before it runs. - Plan ids: a
plan_idmust match^plan_[0-9a-f]{12}$and resolve to a file directly inside<workspace>/planswhoseplan_idfield matches. Anything else is refused. - Content binding:
create_planstoresplan_hash(SHA-256 over the plan id, creation time, snapshot, skipped list, and each action's id, tool, arguments and before value; plans that carry areviewblock, markedhash_version: 2, also cover the canonicalised review andreverts_plan_id). Approving requiresexpected_hash, the hash of the plan the person was shown (the command-line tool computes it from what it printed; the panel sends back theplan_hashfrom the list it rendered).update_plan_staterefuses if the plan on disk does not have that hash, or no longer matches the hash stored at drafting, and storesapproved_hash. Every execution path refuses an approved plan whose content no longer matchesapproved_hash. - Review block: reviewable rationale (summary, reasoning, citations
{rule_id, clause, source}, assumptions, excluded{element_id, reason}, warnings) goes inreview, passed ascreate_plan(review=...)or theplan_actionsreviewargument. It is strict (unknown keys refused, per-field length caps, 64 KB total), stored as given, hashed, and escaped by the command-line tool. Plans without a review keep hash version 1 and still verify; a plan mixing review and version is refused. Keys outside the hash (anything passed inextra, and lifecycle fields such asstate,approved_*,executed_at,results) are metadata, not approved content, andshowlists them.plan_revertwrites conflicts, notes and warnings intoreview. The panel does not renderreview; a panel plan-review card is in an unmerged pull request (#121) and is not shipped on this branch. Useaec-model-bridge-approve show <plan_id>to see the full review. - At most once: every execution path (MCP,
run_asyncat queue time, panel, chat, recipe and module steps,execute_plan) callsApprovalGate.claim_actionbefore the tool runs. Under a per-plan lock (a thread lock plus a file lock), it checks the plan, finds the open action and createsplans/.claims/<plan_id>.<action_id>withO_EXCL, then marks the actionrunning. When the tool returns, the action becomesexecuted; if it raises, it becomesfailedand stays consumed. When no action is open or running, the plan becomesexecuted(all succeeded) orpartial. A failed action needs a new plan. - Humans approve:
approve_plan,reject_planandrollback_planstay registered but are not listed to MCP clients and are refused by the shared dispatch (security/dispatch.py) used by MCP, the panel chat, module tool executors and the panel route, and byApprovalProvider.execute_toolitself. A plan cannot contain them. They run only throughApprovalProvider.execute_human_tool, which the panel route calls withvia="panel", or through the command-line tool (via="cli"). The channel is set by the route;approver/approved_viaarguments are ignored andapproved_byis the OS account of the approving process. approval_mode: the value is trimmed and lower-cased and is one oflook_only,ask_first(aliasrequired) orauto. Onlyautodisables the gate.look_onlyrefuses every tool that changes the model, on every path, includingrollback_plan. Unknown values behave asask_firstand log a warning.- Limits: none of this authenticates the human. A process that can run shell commands as the user can run the command-line tool with
--yes. The panel's/executeendpoint authenticates a local process, not a person: it relies on the Host/Origin/Content-Type checks and on a per-user token file (see security), and any process running as the same user can read that token. Software with write access to<workspace>/planscan replace a plan together with its stored hashes or remove claim files. - Pending only in the panel: the panel's Plans list is fed by
ApprovalGate.list_pending_plans, so it shows only plans in thependingstate.aec-model-bridge-approve show <plan_id>works for plans in any state (listcovers pending plans only).proofs/<plan_id>.jsonexists only for executed (or attempted) plans; approved-but-unexecuted and rejected plans have no proof bundle. - Auto-Approval: For headless CI/CD pipelines,
approval_mode=autocan be set via environment variable (MCP_REVIT_APPROVAL_MODE=auto).
4. Rollback Strategies
- Revit Undo (
undo): Design target, not built. The intent is one named transaction per plan ("AMB: Plan <plan_id>"), so that a single Ctrl+Z reverts the whole plan. Today the add-in names one transaction per action (for example one per parameter write), so undoing a plan takes one Ctrl+Z per action. A one-step undo for a whole plan is planned. Live-Revit behaviour is UNVERIFIED. - Inverse Counter-Plan (
inverse): For persistent history rollbacks, the hub records the before-state (e.g., parameter values) androllback_planwrites those values back in reverse order. An action with no recorded before-value (including an empty one) is skipped and reported as a warning, so a rollback can be partial.plan_revertdrafts the same reversal as a new plan that needs approval. Live-Revit behaviour is UNVERIFIED. - Irreversible (
none): High-risk operations (e.g., deleting models, file outputs) cannot be rolled back. A separate second confirmation for them is planned, not built: today they go through the same single approval as any other plan.
Consequences
- Trust & Safety: Reduces the risk of hallucinated or malicious AI writes damaging BIM models. The gate is enforced in the hub; behaviour in a live Revit session is UNVERIFIED.
- Audit Trails: Every write corresponds to a versioned ActionPlan, a specific approving user, and an audit ledger entry.
- Decoupled Orchestration: AI agents can generate plans asynchronously while running long-running processes (e.g., clash detection), leaving the execution to the user.