4.3 Connect to cmBuilder MCP

Available with the following Subscriptions: All Subscriptions
Available to enable for the following Company Roles: Admin
Available to connect for the following Company Roles: All roles

The cmBuilder MCP server connects an external MCP client to a cmBuilder Company Space. It can be used to search the Resource catalog and read or edit the current scene if used in a Scenario. Authorization uses OAuth, which does not require client sign-in to include pasting a token.

💡Note: MCP must be enabled for the Company Space before Scenario based MCP functionality is available. Keep one Scenario tab open while frontend tools run.

This article contains the following sections:

1. Enable MCP for the Company
2. Connect an MCP Client
3. Use Frontend Scenario Tools
4. Available Tools
5. Disconnect or Disable MCP
6. FAQ

Enable MCP for the Company

cmBuilder MCP can be enabled at the company level by a Company Admin. Enabling MCP makes the server available for authorized users in that Company Space. Disabling MCP hides Scenario MCP options and blocks new MCP use for the company. From the homepage the setting can be accessed by: 

1. Clicking on Company settings (1), then selecting the AI & Integration (2) from the left menu. 
2. Locate the company MCP setting and switch on Enable MCP Server access (3). 
3. Confirm MCP options are available in a Scenario after the setting is on.

💡Note: When MCP is disabled for the company, Scenario MCP menu items stay hidden.

Connect an MCP Client

Connect from any MCP client that supports OAuth. Enter the MCP server URL for the company region and the matching App or App2 environment. The client discovers the cmBuilder authorization endpoints and opens a consent screen. Approve only the access required for the selected tools.

Use the MCP server URL that matches the company region and App or App2 environment. 

• Frontend Scenario tools require the App URL.
• Company region is listed in the URL of the Scenario: app-au/app-uk/app-eu, all others are us region.  

1. In the MCP client, start a connection to the cmBuilder MCP server. Enter the URL taking into account the company region (US/UK/EU/AU) and environment (App or App2).
2. Set authentication to OAuth. If the client requires a client ID, enter "cmbuilder-mcp-client". Leave the client secret and scope blank.
3. Sign in to cmBuilder when prompted.
4. Review the consent screen. Confirm the application name, the company, and the access level for each tool group. Projects lists and accesses Projects, settings, and metadata. Site plan & 3D Content views and manages Scenarios and 3D objects. For each group, select None, Read, or Read & write.
5. Approve access. The client shows the MCP server as connected. Do not paste a token.

💡Note: Enabling a tool that already matches the granted access does not show the consent screen again. Enabling a tool that needs additional access starts a new authorization request. Select Read unless write access is required.

Use Frontend Scenario Tools

Catalog search tools run against the cmBuilder Resource library. Frontend scene tools run in the open, signed-in Scenario tab. Open the Scenario and enter the required editing mode before the client calls a scene tool.

1. Enable MCP for the company and connect the MCP client.
2. Open the target Scenario in one browser tab and sign in as the same user who authorized the MCP connection.
3. Enter the editing mode required by the tool, such as massing, laydown, resource placement, or Smart Template editing.
4. Leave that tab open. Do not edit the scene in that tab while a frontend tool is running.
5. Ask the MCP client to inspect or edit the current Scenario.

💡Note: Frontend tools use the tab's current Milestone, active Smart Template, and editing mode. Keep exactly one eligible tab open for that user and Scenario. Extra tabs cause the call to fail. A busy tab rejects overlapping calls instead of queueing them.

Available Tools

The MCP server exposes catalog tools and frontend scene tools. 

• Catalog tools do not require an open Scenario tab. 
• Frontend scene tools require an open tab and the matching editing mode.

Catalog Tools

Use catalog tools to search and inspect the Resource library.

Frontend Read Tools

Read tools inspect the open Scenario. They do not change saved scene data.

Frontend Write Tools

Write tools change the open Scenario. They require an authorized MCP connection with write access.

💡Note: A rejected or failed save is reported as a failure. A timeout or disconnect after a write starts can leave the outcome unknown. Inspect the Scenario before repeating the action.

Disconnect or Disable MCP

Remove MCP access from the client or from the company. Disconnecting the client invalidates that connection. Disabling MCP for the company hides Scenario MCP options and blocks new MCP use.

• In the MCP client, disconnect the cmBuilder MCP server. Later tool calls fail until the client is reconnected and approved again.
• To stop MCP for the whole Company Space, turn off the company MCP setting in Company Settings.

💡Note: Reducing access takes effect immediately and does not show the consent screen. Reconnecting after a disconnect requires a new authorization.

FAQ

Why did a frontend tool fail?
Confirm MCP is enabled for the company, the MCP client is connected, and exactly one matching Scenario tab is open. Confirm the tab is signed in as the authorizing user, is in the required editing mode, and is not already running another tool.

Do catalog tools need an open Scenario?
No. Catalog search and Resource lookup run without an open Scenario tab. Frontend scene tools require an open tab.

Does disconnecting the MCP client remove access?
Yes. After disconnect, later MCP tool calls fail until the client is reconnected and approved again.