How it works

confirm_token is a two-step handshake with the AI app. The AI app is expected to show the action to you; Model MCP does not show its own dialog. The token does not prove human approval.

The Python server runs beside the MCP client and communicates over stdio. The add-in runs inside Revit on Windows and reads the active document through an ExternalEvent. A remote client can use HTTP with a bearer token or the SSH file channel.

Compatibility

The add-in targets the lowest stable Revit API build of each supported year for compatibility with every patch of that year.

First call

1. Revit loads RevitModelMcp.addin and starts a file watcher, heartbeat and optional HTTP listener.
2. The MCP client calls revit_ping; the server constructs {"command":"ping"}.
3. HTTP queues the job in memory; local or SSH mode publishes it as job_<jobId>.json in the per-process directory of the Windows channel directory.
4. An ExternalEvent invokes the shared command handler on Revit's API thread.
5. The handler returns success:true with data:"pong"; the server delivers the JSON result over MCP.

The channel directory defaults to %LOCALAPPDATA%\RevitModelMcp. The add-in loads directly through its manifest and does not require a separate loader. The feed format documents paths and response fields.

Read-only and actions

The default tools read model data or export a view to PNG. Exports and diagnostics write files outside the Revit model. Actions run by default; a committed change assimilates into one named, undoable Revit change and reports a summary. One workstation read-only lock refuses actions without hiding the tools. Turn it on with the Read-only ribbon button or revit_set_read_only; turning it off with the tool needs a two-step AI app token handshake. The AI app is expected to show the action; Model MCP does not show its own dialog. The token does not prove human approval. The machine policy wins over the lock. Turning the lock off re-enables action execution without restarting Revit. Either read-only setting is checked independently; direct HTTP callers require the token and are refused while the workstation read-only file exists.

Selection and navigation use UI calls. Model changes and temporary isolation run in individual transactions. revit_run_actions groups the per-step transactions in a TransactionGroup with one undo entry on success and one rollback of the group on failure or a batch dry run. Warnings are dismissed and reported on success; unresolved errors roll back the action. Action handling attempts TaskDialog overrides and reports their messages. The tools do not save the model.

Routing and waiting

HTTP defaults to 127.0.0.1:53110; the bearer token is stored in the per-user settings.json. Each HTTP endpoint belongs to one Revit process. A tunnel can connect a remote client while the listener stays on loopback. See transport configuration for LAN and Tailscale routes.

Local and SSH modes run Windows PowerShell under the Revit account. They locate responses by command and filename; they have no request correlation ID. Use one server process per file channel directory and a distinctive document filter for multiple Revit instances. HTTP polls by job ID. Completed read results are retained for ten minutes and action results for 24 hours; see result retention. Timeouts do not cancel accepted jobs, especially actions.

The architecture describes scheduling and failure behavior. The server reference lists environment settings.

Model naming defaults

Queries and catalog lookups accept names from the active document. The snapshot and view dump use the following generic defaults:

Data	Default
View dump profile parameters	Names starting with Project_, matched without case sensitivity; instance values take precedence over type values
View dump measurements	Length, Thickness, Area, and Volume, matched without case sensitivity; lengths are reported in millimeters, areas in square meters, and volumes in cubic meters
Snapshot regions	Family instances whose family name contains Region, matched without case sensitivity
Region comments	Named parameters Comment 1 and Comment 2
Annotation parameters	Built-in Mark, plus named parameters Segment, Number, and Zone Code
Curtain panel parameters	The annotation parameters plus NameOverride
View counts	Non-template views with the case-sensitive prefixes Coordination_ and Construction_
Section prefix labels	Case-sensitive leading text Coordination or Construction; all other names receive other

Missing annotation, curtain panel, and profile parameter values are omitted; missing region comments are null. The snapshot exposes regions, regionCount, region comment1 and comment2, model counts totalRegions, coordinationViews and constructionViews, and panel statistics panelsWithSegment and panelsWithNumber. Model names and localized category labels are returned as stored in Revit.