RevitDocs.Mcp: Stop AI from Making Up Revit APIs

When AI writes Revit plugin code, the most common failure scenario isn't flawed logic—it's inventing an API function name that doesn't exist at all, or using an API from an old version that was deprecated long ago in the current Revit release. The Vietnamese YouTube channel Kỹ Sư Giấy (Paper Engineer) recently showcased an MCP server project called RevitDocs.Mcp, designed specifically to solve this pain point.

The Root Cause: Revit API Changes Yearly, AI Training Data Can't Keep Up

The Revit API is not static. Autodesk releases API updates with each new Revit version every year—functions may be renamed, deprecated, or replaced. AI models are trained on a mix of documentation and community code from multiple versions, causing them to frequently "mix up versions" when generating code. The resulting code looks reasonable but fails to compile.

What's worse, Revit API official documentation and code examples are scattered across multiple sources with varying quality. Manually searching documentation is already time-consuming enough for developers—expecting AI to "remember" the correct version is wishful thinking.

Why Large Models "Mix Up" API Versions

Large language models derive their knowledge from training corpora, which are snapshots at a point in time. Revit has released over 20 major versions since 2005, each with API additions, removals, and modifications. Training data mixes blog posts, Stack Overflow answers, and GitHub repositories from different eras—Revit 2018, 2020, 2023, and beyond. The model cannot distinguish which code snippet corresponds to which version.

More critically, the model doesn't "know" which version it's referencing—it's simply doing probabilistic token prediction. When a user says "create a wall using the Revit API," the model outputs the function name that appears most frequently in its training corpus, which may belong to a long-deprecated version. This type of error is called "API hallucination" and is equally prevalent in frequently iterating SDKs like SolidWorks, AutoCAD, Unity, and Unreal.

Retrieval-Augmented Generation (RAG) is the general solution to this problem: have the model retrieve relevant content from authoritative data sources before generating. RevitDocs.Mcp essentially turns RAG into an MCP server, making the "look up documentation" step explicit and tool-based, rather than buried inside the model.

What Is RevitDocs.Mcp

RevitDocs.Mcp is a server based on the MCP (Model Context Protocol), developed by the Kỹ Sư Giấy team. Its core approach is straightforward: before AI writes code, make it look up the documentation first.

MCP is an open protocol introduced by Anthropic that allows AI agents to connect to external tools and data sources. Any AI client that supports MCP can connect to this server, and it doesn't require any AI vendor API keys—the server itself only retrieves documentation and doesn't call large language models.

The server runs outside of Revit, communicating with local AI clients via STDIO, completely decoupled from the Revit process.

More Background on the MCP Protocol

MCP (Model Context Protocol) is an open standard released by Anthropic in late 2024, aiming to unify how AI models interact with external tools and data sources. Before MCP, integrating a new data source (database, file system, API) often required writing adapter code separately for each AI client. MCP standardizes this abstraction layer: the server side only needs to implement the protocol once, and any MCP-compatible client (such as Claude Desktop, Cursor, Cline, etc.) can call it directly.

MCP primarily supports two communication methods: STDIO (standard input/output, suitable for local processes) and SSE/HTTP (suitable for remote services). RevitDocs.Mcp chooses STDIO, meaning it's launched as a local subprocess by the AI client and exchanges JSON-RPC messages via stdin/stdout. This mode offers low latency, requires no network ports, and needs no cloud services—particularly suitable for desktop development scenarios like Revit.

MCP servers typically expose three types of capabilities: Tools (callable functions), Resources (readable data), and Prompts (preset prompt templates). RevitDocs.Mcp's four tools fall under the Tools category, and all are designed as read-only to prevent AI from accidentally modifying the local environment.

Four Read-Only Tools, Covering Everything from Doc Search to Code Discovery

RevitDocs.Mcp provides four tools, all read-only operations:

Revit Docs search — Searches API documentation based on the user-specified Revit version. The version is an explicit parameter—AI must clearly declare the target version to avoid cross-version confusion.

Revit Docs read — Reads the specific documentation page content from search results, providing complete function signatures, parameter descriptions, and usage.

Revit Codes search — Searches example code from vetted code sources. These sources are curated and far more reliable than code AI "recalls" from training data.

Revit Docs sources — Lists currently available documentation sources and their status, letting developers clearly know what coverage the retrieval provides.

Why "Version" Must Be an Explicit Parameter

In Revit API development, the same operation may be written completely differently across versions. For example, certain overloads of FilteredElementCollector, parameters of Document.Create methods, and the subclass hierarchy of various Element types all evolve with versions. If AI doesn't declare the target Revit version, the retrieval layer can only return mixed results from multiple versions, which actually worsens confusion.

Making version a required parameter is equivalent to forcing the agent to make a "version decision" first—it must know which Revit the user is using before initiating retrieval. This is a "constraint as prompt" design philosophy: constraining AI behavior through interface signatures is more reliable than repeatedly reminding it to "watch the version" in prompts. Similarly, the "Revit Docs sources" tool lets the agent understand what sources the retrieval covers, preventing it from being overconfident about uncovered areas.

This approach of encoding domain constraints into tool design is worth emulating by other CAD/BIM MCP servers.

Installation and Deployment: Currently Requires Self-Build

RevitDocs.Mcp has not yet released an official version; users need to build from source. The project is based on .NET 10—clone the repository and run the publish script.

The deployment process has three steps: clone the project and run the publish script, configure the executable path in the MCP client, and ensure the agent calls RevitDocs search to look up function names before writing code.

According to the video, the project accumulated 27 commits within 30 days, indicating a fairly active development pace.

Multi-Source Cross-Validation

You may not have noticed that the above information comes from a single source—a video introduction by Kỹ Sư Giấy. Independent verification and third-party reviews of this project in the developer community have not yet appeared. Details such as the project version number, specific API coverage, and the complete list of documentation sources need to be confirmed by developers themselves by checking the repository.

The Significance of Such Tools

RevitDocs.Mcp represents a broader trend: using the MCP protocol to "connect" domain knowledge to AI agents, rather than expecting models to memorize all details during training. For professional software with frequently changing APIs (Revit, AutoCAD, Blender, etc.), this on-demand retrieval approach is more flexible and reliable than fine-tuning models.

For Revit developers, the core question is simple: before you let AI write code, did you make it look up the documentation first?

(This article is based on content from the YouTube channel Kỹ Sư Giấy's video. For project details, please refer to the official repository.)