How to Set Up a Revit Cloud Worksharing Migration Workflow with APS and MCP

What will you learn in this guide?

This guide explains how to approach a Revit Cloud Worksharing (RCW) migration workflow in a Model Context Protocol (MCP) server that communicates with APS. Autodesk’s example shows how an MCP client turns a natural-language request into tool calls, how the server orchestrates APS operations, and how Revit automation migrates the model. The steps here are intended to explain the example architecture; they are not a production-ready setup recipe that can be applied directly to every project.

The key distinction is that the AI client coordinates the migration decision and tool calls, while the actual operation on the model runs through Design Automation for Revit using the Revit API. The MCP server manages the operations and authorization between the two sides.

Requirements and access

Autodesk’s example extends an MCP server built on Node.js with APS functionality. The MCP server must connect to a compatible client and have access to the APS data containing the source model and target project. The Revit engine and automation activities must also be configured to run the migration. Since the source does not specify a particular Node.js version or pricing information, no assumptions about version or cost should be made here.

The choice of authentication depends on where the server runs and whose data the operation uses. For a server launched by a local desktop client over STDIO, separate authentication at the client-server layer may not be necessary. For operations in APS on behalf of a user, 3-legged OAuth (3LO) or PKCE can be used in environments such as local processes where a client secret cannot be stored. For work requiring an application identity shared across the server, 2-legged OAuth (2LO) or an authorized Secure Service Account (SSA) can be considered. Keep in mind that not every API accepts every authentication type.

Planning the migration workflow step by step

1. Define the use case and client. First, clarify whether the workflow will use the user’s own access or a shared automation identity. Then decide whether the MCP server will run as a local process or be made available remotely over HTTP. Autodesk’s guide covers STDIO for local use and Streamable HTTP for remote, multi-user scenarios. For servers exposed over HTTP, authentication between the client and server should be designed separately from APS authentication.

2. Choose the APS authentication method based on the required permissions. Consider 3LO or PKCE, which rely on a user signing in, to access personal user data. 2LO can be used for an application’s own resources, but may not be sufficient for API calls that require user context. If automation needs to access project data without requiring a user to keep signing in, consider an SSA authorized for the target hubs and projects. Don’t confuse the access token used between the server and client with the APS token; the tokens serve different purposes at each layer.

3. Separate the responsibilities of MCP tools. In Autodesk’s example, the server can discover projects and folders using existing data management tools; the extensionType field in folder contents helps identify RCW models. The migrate-rcw-model tool added for migration takes the source model, target project and folder, and target Revit version. The application uses this information to prepare and submit an APS Automation job. Separating discovery from the data-changing migration action makes it clear to the client which operation it is about to start.

4. Check prerequisites and get user confirmation. In the example workflow, check-migrator-setup checks the configured Revit engines and automation activities. Autodesk notes that workflow instructions can guide the assistant to check prerequisites and ask the user for confirmation before migration. Don’t submit the migration job until the target project, folder, and Revit version are clear; verify these choices against the user’s request.

5. Make the asynchronous job trackable. A migration can take several minutes, so receiving a job ID from the tool does not mean the job is complete. In the example, get-migration-status returns the job status and error information; cancel-migration requests cancellation of pending jobs. On compatible clients that use MCP Apps, a status panel can show active jobs, completed migrations, error details, and cancellation controls. This layer should be considered separately from the tool that starts the migration job.

6. Test the workflow safely and within scope. First, verify that accessible models can be listed and that the configuration check works. Then, with user approval, submit a single model to the target project and check that the job ID, status, and error information are returned as expected. Passing APS tokens to the client or forwarding the client token directly to APS is not the right approach. For a remote MCP server, also define who can access the server; this is separate from the layer that determines which identity APS uses for operations.

What this means for architecture and visualization workflows

Architecture firms working with multiple Revit projects or RCW models may benefit from the ability to start migrations in natural language and track progress in the same client. For developers, MCP tools provide an example of connecting existing APS automation to different compatible clients. However, this does not automatically solve BIM coordination or the analysis of model dependencies.

The sources provide no information about hardware or licensing costs. Before making a decision, verify the firm’s APS access, the selected Revit automation configuration, and whether the authentication method is compatible with project permissions. In particular, teams working with linked models should not assume that the associated models will also be migrated.

Common mistakes and next steps

The most important limitation is that the example focuses on individual RCW models: it does not automatically migrate linked model relationships or repair links in the target project. Projects containing linked models require separate dependency analysis, preflight checks, and coordination; the source treats these as capabilities that could be added in the future.

Another common design mistake is treating authentication between the MCP client and server as the same thing as access to APS. First, establish which party authenticates to whom at each layer. Then review the tools, permissions, and user confirmation requirements with that distinction in mind. When moving to implementation, use Autodesk’s example repository and APS MCP authentication examples as starting points; address security and linked-model requirements separately for production.

Sources and license

This content is adapted from Autodesk Platform Services guides “Bringing Revit Cloud Worksharing Migration to AI Assistants with APS and MCP”, “Building Custom MCP Servers with Autodesk Platform Services”, and “Authentication Patterns for APS MCP Servers”. The supplied source records list the license status as free, but do not specify a particular open license; accordingly, the content is not described as published under a license such as CC BY.