APS ACC

This MCP Server lets you access Autodesk Construction Cloud data from within your coding environment using natural language queries. It translates your questions into APS API calls, returning structured results that you can use to build automation, dashboards, and custom tooling without leaving your editor.

How to use

You connect an MCP client (such as the IDE chat assistants) to the APS MCP Server running in your workspace. The server authenticates with a Secure Service Account and exposes tools that let you browse projects, files, issues, and RFIs through natural language. In your editor or chat client, you ask questions in plain English and the server returns data you can act on in code or dashboards.

Key usage patterns include: querying the list of accessible projects, inspecting folder contents, listing and drilling into issues, and creating new records like issues or RFIs. You use these through your IDE’s Copilot/Claude/Cursor-like experience, and the results are formatted for easy consumption in your development workflow.

How to install

Prerequisites you need before starting:

• Node.js is installed on your machine
• An APS application that is of type Server-to-Server is provisioned
• You have access to Autodesk Construction Cloud (ACC) for your APS app

Install and start the MCP server locally by following these steps.

bash
# 1. Clone the MCP server repository
git clone https://example.com/aps-acc-mcp-server.git
cd aps-acc-mcp-server-nodejs

# 2. Install dependencies
yarn install

# 3. Create and populate environment variables
# See the environment variable list in the next step or use your own secure values

# 4. Start the server (the final runtime command). If you build locally, ensure you run the start script or node server as shown in the examples.
node server.js

Configuration and environment

You configure authentication using a Secure Service Account and provide its credentials to the server. The server reads values from environment variables for APS access and SSA (Secure Service Account) information.

APS_CLIENT_ID=your-aps-client-id
APS_CLIENT_SECRET=your-aps-client-secret
SSA_ID=your-service-account-id
SSA_KEY_ID=your-private-key-id
SSA_KEY_PATH=/path/to/your/private-key.pem

Developer wiring for IDE integrations

To connect IDE clients, you expose the MCP server via stdio or through an explicit MCP URL if you have one. The common local wiring shown uses node to run a server.js file located in the project path.

// VS Code MCP Client example
{
  "servers": {
    "aps_mcp_node": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/aps-mcp-server-nodejs/server.js"]
    }
  }
}

// Claude Desktop example
{
  "mcpServers": {
    "aps_mcp_nodejs": {
      "command": "node",
      "args": ["/path/to/aps-mcp-server-nodejs/server.js"]
    }
  }
}

Examples of typical prompts

Ask questions like “What projects do I have access to?”, “Show me issues for project X,” or “List folder contents under path Y.” The MCP server returns structured data that you can use to drive code, dashboards, or further automation.

Notes on security and permissions

All data access is performed through the Secure Service Account credentials you configure. Ensure the service account has the minimum required scope for the tasks you intend to perform and invite that account into the ACC projects it needs to access.

Troubleshooting tips

If the server fails to start, verify that the environment variables are correctly set and that the SSA private key path is accessible. Check that the APS client credentials are valid and that the Service Account has the necessary ACC permissions.

Notes on future enhancements

The MCP Server is designed to support expanding tool coverage, adding webhooks for IDE notifications, and enabling more advanced queries and cross-project operations as you integrate it into your workflows.

Available tools

getProjectsTool

Retrieves all ACC accounts and projects accessible to your service account and returns a list of accounts with nested projects (IDs and names)

getFolderContentsTool

Browses folder and file structure within a project and returns folders and files with IDs and display names

getIssuesTool

Fetches all issues from a project with details like IDs, titles, statuses, types, assignments, due dates, and 3D coordinates

getIssueTypesTool

Gets available issue types and subtypes for classifying issues

createIssueTool

Creates a new issue in a project and returns the created issue details including IDs and timestamps

getIssueDetailsTool

Retrieves detailed information about a specific issue including description, assignee, dates, location, comments, attachments, and audit trail

updateIssueTool

Updates an existing issue with provided fields and returns updated details

addIssueCommentTool

Adds a comment to an issue and returns a confirmation with ID and timestamp

addIssueAttachmentTool

Documents how to attach files to issues (requires Data Management API)

listRFIsTool

Retrieves all RFIs from a project with IDs, titles, questions, statuses, assignments, and due dates

getRFITypesTool

Gets available RFI types and categories for classification

getRFIDetailsTool

Retrieves full details of a specific RFI including question, responses, attachments, and history

createRFITool

Creates a new RFI in a project and returns its IDs and timestamps