Revit MCP guide · Reference

Troubleshooting

The things that go wrong, in the words you will see, and what to do about each.

Claude does not list the Revit tools

You ask about Revit and the assistant answers as if it has never heard of your model, or says it has no tool for that.

  1. Claude Desktop: quit it fully, then start it again

    Right-click its icon in the Windows tray and choose Quit. It only reads its list of servers when it starts.
  2. Still nothing? Connect it again

    Run the connect line from Connect Claude.
  3. Claude Code: check the server is listed

    claude mcp list
    You should see revit-pro. If not, run the add line from Connect Claude.

It says no Revit is running

The assistant found the server, and the server could not reach an add-in inside Revit.

  • Revit must be running, with the lAvArt tab present and a project open.
  • Revit and your assistant must run as the same Windows user. The two talk over a connection that belongs to one user, so an assistant started “as administrator”, or in another session, cannot see your Revit.
  • If Revit was started after the assistant, just ask again: the server looks for Revit on every request.
  • Several Revit windows open? The assistant is told so and asks which one.

The lAvArt tab is not in Revit

  • Revit asked whether to load the add-in and the answer was Do Not Load. Close Revit and start it again; choose Always Load. See Revit’s Always Load prompt.
  • The installer ran while Revit was open. Close Revit and run the installer again.
  • Your Revit version was not ticked in the installer, or is not one it covers. See below.

Windows blocked the installer

A blue Windows protected your PC window is expected for the unsigned beta: choose More info, then Run anyway. The steps, and what to do if your practice does not allow unsigned software, are on Install.

If there is no Run anyway button, your IT policy blocks it outright. Send your IT contact this page, or write to info@lavart.ai.

My Revit version is not offered

The published installer covers Revit 2025 and 2027. It only offers the versions it finds installed on the computer. Other versions are not supported yet; tell us which one you run, because that decides what we build next: info@lavart.ai.

It refuses to change something

A refusal is the add-in doing its job. The usual ones:

  • The document is Read only. Set Permission to Allow edits on the lAvArt MCP panel. See Let it edit.
  • It needs Pro. The message reads “<tool> needs lAvArt MCP for Revit Pro (feature <feature>).” and the hint “Start the free trial or enter a key at https://revit.lavart.ai/revit-mcp”. See When a tool says it needs Pro.
  • A central model is open directly. Open a local copy.
  • The AI is paused. Press Pause AI again to resume.
  • Revit is busy. A dialog or a command is open in Revit. Close it and ask again.

Every message, and what it means

When something does not go through, the assistant is given a short code and a sentence. It usually explains in its own words; if it quotes the code, this is what it means.

no_revit
No Revit with the add-in is running on this computer, or its connection dropped.Start Revit, open a project, and check the lAvArt tab is there.
multiple_instances
Several Revit processes run: pass instance (one of the pids in details).Tell the assistant which Revit you mean, or close the other one.
no_document
Revit has no project open, or document names no open document.Open a project in Revit.
revit_busy
Revit did not answer in time (a dialog or a command is open), or too many requests wait.Close the dialog or finish the command that is open in Revit, then ask again.
expired
The call waited past its deadline, or was cancelled, and was not run.Ask again.
tier_denied
The permission set in Revit for this document does not allow this tool. A permission stored from an earlier Revit session, or written into the settings file while Revit runs, counts only once the person confirms it in this Revit (details.waitsForClick, details.stored; fix ask_human).Set Permission for this document on the lAvArt MCP panel.
licence_required
The licence lacks a feature the call needs: details.feature names it (write or destructive: Pro; mep: creating or reshaping MEP elements, details.ids lists them).Start the free trial, or enter your key in Revit.
preview_required
apply needs the changeToken of a preview of exactly these arguments.Let the assistant preview the change first.
token_stale
Something the preview read (a target, a host, a level, a type) changed since the preview, by the person or by another apply, so this apply was refused and nothing was changed. Preview again and apply with the new changeToken. Apply dependent steps one after the other, never in parallel: two applies that change the same host (two doors into one wall) cannot both use previews made before either ran; the second answers this and is previewed again after the first.The model changed since the preview: preview again.
confirmation_declined
The person declined the change in Revit's confirmation window (a destructive apply, or a write of more than 1 000 existing elements: details.reason, details.answer declined), or this Revit has no confirmation window (no_window, failed: refused, fail closed); for agents_register, the person denied the registration. Nothing was changed; the changeToken is used up. Do not send it again unless the person asks for it: fix ask_human.Nothing was changed. Ask again if you meant to accept.
confirmation_timeout
Nobody answered the confirmation window in Revit within details.minutes (10): it closed as Cancel. Nothing was changed; the changeToken is used up. Ask the person to be at Revit, then preview again: fix ask_human.Nothing was changed. Ask again and answer the window in Revit.
invalid_argument
An argument is wrong: details.field names it.
unknown_category
A category name matches no category of the project: details.nearest suggests some.
not_found
Ids or a set name not found: details lists them.
read_only_document
The document cannot be written (read-only, a family or linked document, or not the active one).Edits go to the active project only, not to a family, a link or a read-only file.
central_model_open
A central model is open directly: writes are refused, open a local copy.Open a local copy of the central model.
owned_by_other
What the call would change is held by another user (worksharing): details.owner names them when Revit says. Elements a call skips for this are listed owned_by_other with their owner. Fix ask_human: they relinquish it.Ask the colleague who owns the elements to relinquish them, then try again.
too_many
More elements than one call may touch: details.cap says the cap.Ask for the change in smaller parts.
revit_refused
Revit rolled the change back: the message carries Revit's reason; nothing was changed.Read Revit's reason in the message. Nothing was changed.
unsupported_in_version
This Revit version cannot do that.That needs a newer Revit.
rate_limited
Too many calls in this Revit: 30 write calls a minute (or the document's hourly breaker), or 240 read and UI calls a minute: wait details.retryAfterSeconds.Wait a moment, then carry on.
paused
The person paused the AI in Revit.Press Pause AI again on the panel to resume.
cancelled_by_user
The call was stopped while it ran: the person pressed Cancel in Revit's progress window (details.by person, fix ask_human) or the client sent mcp.cancel (details.by client). It stopped at a transaction boundary and everything it had done was rolled back: nothing was changed, no undo entry, no change-log entry; details.notDone counts what it did not do. A cancelled apply used up its changeToken.
trial_unavailable
mode trial cannot run in a workshared document (its rollback would leave elements borrowed): preview, then apply. export_ifc answers it there too (Revit's IFC exporter runs in a change the engine rolls back): the person exports IFC from Revit itself (fix ask_human).In a workshared model the assistant previews, then applies.
file_not_allowed
A file path is outside the folders the person allowed in Revit (lAvArt MCP > Folders), or not a plain full path, or an export's folder is not one of them or inside one: details.field names it, details.reason says why. Nothing was read or written.
replay_gone
An apply sent again with its requestKey, but the first apply's work is no longer all in the model (undone, reverted, partly deleted, or not saved): nothing was replayed or changed; details count what is left. Send again with a new requestKey.
budget_exceeded
The call would create more elements than are left of this document's session budget once open plans' shares are set aside (details: budget session, limit, used, reserved, left, adding), or than are left of the share its plan set aside (details: budget plan, plan, limit, used, left, adding). Nothing was created. Only the person raises the document's budget, in Revit (lAvArt MCP > Budgets): fix ask_human.
plan_stopped
The person stopped the plan the call names (lAvArt MCP > AI work): no write that names it runs, previews included, and plan_update cannot change it, until they resume it there. The plan's agents are paused too (the client that made it and its tasks' assignees): with details.agentPaused, the caller is one of them and none of its calls but reads runs in that document, whatever plan it names or none, until the person resumes the plan or lets its agents work. Nothing was changed: fix ask_human.
plans_unreadable
This document's plans file is there but cannot be read now (details.reason: locked, damaged, version, too_large). It is never taken for no plans: plan_set, plan_update and every write that names a plan are refused, and while this Revit has never read the file every call but reads too (what open plans set aside, and which agents a stop pauses, is not known). Nothing was changed and the file is kept as it is. locked is retryable; otherwise fix ask_human: only the person sets the file aside, in Revit (lAvArt MCP > AI work).
pack_off
The tool is in a pack the person switched off in Revit (lAvArt MCP > Tool packs), so it is not in the tool list (details: tool, pack, label, field for a model_batch op). Nothing ran. Only the person switches packs, in Revit; no tool can: fix ask_human, then list the tools again.
agent_required
This connection has registered an agent, so every call must carry its handle as agent (details.reason missing), or the handle given is not one of this connection's agents in this Revit session (details.reason unknown: Revit restarted, the agent was forgotten after an hour without a call). Nothing was run. A lost handle is never shown again: register again (fix: call agents_register).
approval_required
A top-level write or orchestrator agent waits for the person to click Allow in Revit (lAvArt MCP > AI work): nothing was registered. Retryable: once they allow it, the same agents_register call gets its handle; fix ask_human. A read agent needs no approval.
too_many_agents
Another agent writes this document now (details.reason writer, details.writer: one write agent per document; an agent with no call for 10 minutes no longer holds it), or too many agents work at once (agents), or too many registrations of this connection wait for the person (waiting). Nothing was registered or changed.
scope_wider_than_parent
A child agent asked for a role or a scope wider than its parent's (details.field): a child is never wider than its parent. Nothing was registered.
loop_detected
The engine stopped this agent in this document: it sent the same call (the same tool and arguments) 5 times in 15 minutes and it failed the same way each time (details.reason repeat_failure, details.code), or it applied the same change 3 times in 15 minutes and each was reverted (apply_revert). Every call of it there but reads answers this until the person lets it write again, in Revit (lAvArt MCP > AI work); time does not clear it. Nothing was changed: fix ask_human. Changing an argument to get past it is not a way forward.
file_exists
An export's exact name (name) is in use in the folder, or a name and all its numbered suffixes are: exports never overwrite, nothing was written (details.name). Call again with another name or none (a name in use then gets a numbered suffix): fix retry_with.
out_of_date
What the call would change (details.id, a view for graphics_override) was changed or deleted in the central model since this local copy last reloaded (worksharing): nothing was changed. The person reloads latest in Revit; no tool reloads, saves, synchronizes or relinquishes: fix ask_human. Elements a call skips for this are listed out_of_date instead.
not_workshared
The tool works on worksets and this document is not workshared: nothing was changed. Enabling worksharing is the person's decision in Revit; no tool does it: fix ask_human.
no_fitting
mep_connect with onFailure fail: the run's type has no part for a joint (its routing preference or default fittings lack it; mep_catalog shows them). details.joint and details.reason say which. As a joint's code it skips that joint only.
connector_mismatch
mep_connect with onFailure fail: a joint's connectors do not go together (another domain, another system classification, other shapes or sizes without a transition, or a connector joined already). details.joint and details.reason say which. As a joint's code it skips that joint only.
calibration_poor
A calibration frame misses a check dimension or a control point by more than 0.5 % or 25 mm (whichever is larger): details.problems say by how much. The frame is kept as poor and every creation that names it is refused until it is calibrated again.
internal
Anything else: the message says what failed.

Send us the log

Still stuck? Write to info@lavart.ai and say what you asked and what came back. If you can, attach the add-in’s log file. Paste this into the address bar of File Explorer to find it:

%LOCALAPPDATA%\Lavart\RevitMcp\engine.log

The log records what the add-in did and any error it met. It is a plain text file: read it before sending if the project is confidential.

Something here wrong, or missing? Write to info@lavart.ai.