aps-mcp-server-nodejs

Simple Model Context Protocol server built with Node.js, providing access to Autodesk Platform Services API, with fine-grained access control using Secure Service Accounts.

YouTube Video

Overview

This MCP server enables AI assistants (like GitHub Copilot, Claude, and Cursor) to interact with your Autodesk Construction Cloud (ACC) projects through natural language. By connecting AI chat interfaces to APS APIs, you can query project data, browse files, and analyze issues without leaving your development environment.

How It Works

The Model Context Protocol (MCP) creates a standardized way for AI assistants to access external data sources:

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
│   VS Code +     │  MCP    │  aps-mcp-server  │   APS   │  Autodesk ACC   │
│ GitHub Copilot  │ ◄─────► │   (Node.js)      │ ◄─────► │   Projects      │
└─────────────────┘  stdio  └──────────────────┘   API   └─────────────────┘

1. AI Client (VS Code/Claude/Cursor) sends natural language queries
2. MCP Server translates queries into APS API calls using Secure Service Account credentials
3. APS APIs fetch data from your ACC projects
4. MCP Server returns structured data to the AI client
5. AI Client formats and presents the information to you

Available MCP Tools

This server provides 18 tools across multiple functional areas:

Projects & Files (2 tools)

Tool	Description	Parameters	Returns
getProjectsTool	Retrieves all ACC accounts and projects accessible to your service account	None	List of accounts with nested projects (IDs and names)
getFolderContentsTool	Browses folder and file structure within a project	accountId, projectId, folderId (optional)	List of folders and files with IDs and display names

Issues Management (7 tools)

Tool	Description	Parameters	Returns
getIssuesTool	Fetches all issues from a project	projectId	List of issues with IDs, titles, statuses, types, assignments, due dates, and 3D coordinates
getIssueTypesTool	Gets available issue types and subtypes	projectId	List of issue types with subtypes (for issue classification)
createIssueTool	Creates a new issue in a project	projectId, title, issueSubtypeId, status, and many optional fields	Created issue with full details including ID, display ID, and timestamps
getIssueDetailsTool	Retrieves detailed information about a specific issue	projectId, issueId, includeComments, includeAttachments	Complete issue details including description, assignee, dates, location, comments, attachments, custom attributes, and audit trail
updateIssueTool	Updates an existing issue	projectId, issueId, plus any fields to update	Updated issue details
addIssueCommentTool	Adds a comment to an issue	projectId, issueId, body	Comment confirmation with ID and timestamp
addIssueAttachmentTool	Documents the process for adding attachments to issues	projectId, issueId, fileName, fileUrl	Documentation/guidance (placeholder - requires Data Management API)

RFIs Management (4 tools)

Tool	Description	Parameters	Returns
listRFIsTool	Retrieves all RFIs (Requests for Information) from a project	projectId, optional filters: searchText, status, assignedTo, limit, offset	List of RFIs with IDs, titles, questions, statuses, assignments, and due dates
getRFITypesTool	Gets available RFI types and categories	projectId	List of RFI types for classification
getRFIDetailsTool	Retrieves detailed information about a specific RFI	projectId, rfiId	Complete RFI details including question, responses, attachments, workflow history, and linked documents
createRFITool	Creates a new RFI in a project	projectId, title, question, dueDate, assignedTo, and optional fields	Created RFI with full details including ID and timestamps

Photos Management (2 tools) - Read-Only

Tool	Description	Parameters	Returns
listPhotosTool	Retrieves photos and videos from a project with filtering	projectId, optional: createdFrom, createdTo, mediaType, limit, offset	List of photos/videos with IDs, names, types, creation dates, and URLs
getPhotoDetailsTool	Retrieves detailed information about a specific photo or video	projectId, photoId	Complete photo/video details including metadata, location, tags, and custom attributes

Note: Photos tools require 3-legged OAuth authentication. Run npm run oauth-login before using these tools. See OAUTH_SETUP.md for details. Important: ACC Photos API v1 is read-only. Photo uploads must be done through ACC Mobile App or Web Interface.

Submittals Management (3 tools) ⭐

Tool	Description	Parameters	Returns
listSubmittalsTool	Retrieves all submittals from a project with filtering	projectId, optional: status, type, assignedTo, limit, offset	List of submittals with IDs, numbers, titles, statuses, types, due dates, and assignments
getSubmittalTypesTool	Gets available submittal types configured in the project	projectId	List of submittal types with IDs, names, codes, and workflows
createSubmittalTool	Creates a new submittal in a project	projectId, title, submittalTypeId, dueDate, optional: number, description, assignedTo, status	Created submittal with full details including ID, number, status, and timestamps

Note: Submittals tools require 3-legged OAuth authentication. Run npm run oauth-login before using these tools. See OAUTH_SETUP.md for details.

VS Code MCP Client Integration

When you use this server with VS Code + GitHub Copilot:

1. Configuration: The .vscode/mcp.json file tells VS Code where to find the MCP server
2. Connection: VS Code starts the Node.js server and connects via stdio (standard input/output)
3. Authentication: The server uses Secure Service Account credentials from .env for API access
4. Tool Discovery: Copilot learns what tools are available from the server
5. Natural Queries: You ask questions in Copilot Chat using plain English
6. Tool Execution: Copilot decides which tools to call and with what parameters
7. Response: Results are formatted and displayed in the chat interface

Example interaction:

You: "What projects do I have access to?"
Copilot: [calls getProjectsTool] → "You have 1 project: Construction: Sample Project..."

You: "List all issues"
Copilot: [calls getIssuesTool with projectId] → "You have 3 open issues..."

You: "Show me details of issue abc123"
Copilot: [calls getIssueDetailsTool] → "Issue: Concrete Surface Finish... Status: Open..."

You: "Create a new issue for the Level 2 rework"
Copilot: [calls createIssueTool] → "✅ Issue created successfully! ID: xyz789..."

You: "List all RFIs in my project"
Copilot: [calls listRFIsTool] → "You have 5 RFIs: 2 open, 3 answered..."

You: "Create an RFI about the concrete specifications"
Copilot: [calls createRFITool] → "✅ RFI created successfully! ID: rfi-001..."

You: "Show me photos from this project"
Copilot: [calls listPhotosTool] → "Found 12 photos: Site inspection, Foundation work..."

You: "Get details of photo abc123"
Copilot: [calls getPhotoDetailsTool] → "Photo: Site Inspection... Created: 2025-01-10..."

Comparison with ACC Native Features

Feature	ACC Web Interface	ACC Project Beta	APS MCP Server
Access Method	Web browser	Web browser	AI chat in IDE
Query Interface	GUI navigation	Conversational AI	Conversational AI
Integration	Standalone app	Standalone app	Embedded in VS Code/Claude/Cursor
Authentication	User login	User login	Service Account (programmatic)
Data Access	Full ACC features	Limited to conversation context	API-based (read and write access)
Customization	Fixed UI	Fixed AI behavior	Custom tools & scripts
Use Case	Manual project management	Quick queries & assistance	Developer workflows & automation
Multi-Project	Switch between projects	Context limited	Access all authorized projects
Offline Mode	❌ No	❌ No	❌ No (requires API)
File Upload	✅ Yes	✅ Yes	❌ No (read-only for files)
Issue Creation	✅ Yes	✅ Yes	✅ Yes (implemented)
Real-time Collaboration	✅ Yes	Limited	❌ No

Key Differences:

• ACC Project Beta: Autodesk's native AI assistant integrated into the ACC web interface, designed for project managers and teams working directly in ACC
• APS MCP Server: Developer-focused tool that brings ACC data into your coding environment, ideal for:
  • Building automation scripts
  • Creating custom reports
  • Integrating ACC data with other systems
  • Quick project status checks without leaving your IDE
  • Prototyping new ACC integrations

When to use each:

• Use ACC Web Interface for full project management, file uploads, and team collaboration
• Use ACC Project Beta for quick questions while working in ACC web
• Use APS MCP Server for development workflows, custom automation, and IDE-native queries

Customer Value & Use Cases

🎯 Value Proposition

The APS MCP Server bridges the gap between construction data and AI-powered development tools, enabling customers to:

1. Reduce Context Switching - Access ACC data without leaving your IDE
2. Accelerate Development - Build integrations faster with AI assistance
3. Improve Data Visibility - Query project data conversationally in natural language
4. Enable Automation - Foundation for building custom workflows and scripts
5. Prototype Rapidly - Test API integrations before full implementation

👥 Target Customer Segments

1. Construction Technology Teams

Organizations building custom integrations on top of ACC:

• Pain Point: Manual API exploration and testing is time-consuming
• Solution: Query ACC data conversationally while writing integration code
• Example: "Show me the issue schema for this project" while building an issue tracking integration

2. BIM/VDC Developers

Developers creating automation for construction workflows:

• Pain Point: Need to understand project structure before writing automation scripts
• Solution: Explore project data, folder structures, and issue patterns without leaving the code editor
• Example: "List all RVT files and their locations" while building a model coordination script

3. System Integrators

Teams connecting ACC with other enterprise systems (ERP, PM tools):

• Pain Point: Understanding data models and testing connections across multiple systems
• Solution: Quick data validation and testing during integration development
• Example: "What fields are available in issues?" while mapping data between systems

4. DevOps/Infrastructure Teams

Teams managing APS applications and monitoring project health:

• Pain Point: Need quick insights without building full dashboards
• Solution: Ad-hoc queries for monitoring and troubleshooting
• Example: "How many open issues are in production projects?" for health checks

5. Independent Developers/Consultants

Freelancers building APS solutions:

• Pain Point: Limited time for API exploration and testing
• Solution: Rapid prototyping and validation of ideas
• Example: Test API responses before committing to implementation approach

💼 Real-World Use Cases

Use Case 1: Rapid Integration Development

Scenario: Developer building a custom dashboard that displays project issues

Traditional Workflow:

1. Open browser → Navigate to APS API docs
2. Set up Postman/Insomnia for API testing
3. Configure authentication
4. Test API endpoints manually
5. Copy response structure
6. Switch back to IDE
7. Write code based on manual testing

With MCP Server:

1. In VS Code: "Show me all issues in my project"
2. Review data structure in chat
3. Ask: "What fields are available for filtering?"
4. Immediately start writing code with accurate data models
5. Time saved: 30-60 minutes per API endpoint

Use Case 2: Project Health Monitoring

Scenario: DevOps team needs to check project status across multiple sites

Query Examples:

"How many projects do I have access to?"
"List all open issues across projects"
"Show me projects with issues overdue by more than 7 days"
"What are the most common issue types?"
"Get detailed information for issue abc123"
"Create a new issue for the concrete rework on Level 2"

Value: Quick health checks without building custom reporting tools

Use Case 3: Debugging Production Issues

Scenario: Support team investigating customer-reported problems

Workflow:

Developer: "What issue types are available in project X?"
Copilot: [Returns actual issue types from customer's project]

Developer: "Show me all issues created in the last 24 hours"
Copilot: [Returns recent issues with details]

Developer: "Get full details for issue abc123"
Copilot: [Shows complete issue information including comments and attachments]

Developer: "Create a test issue to verify the API"
Copilot: [Creates issue and returns confirmation with issue ID]

Developer: "What's the folder structure of this project?"
Copilot: [Shows actual folder hierarchy]

Value: Faster troubleshooting with real-time data access

Use Case 4: Data Migration Planning

Scenario: Migrating data from legacy system to ACC

Queries:

"Show me the folder structure of all projects"
"What custom fields are configured for issues?"
"List all file types in the project"
"Get a sample issue with all its fields to understand the data structure"
"Create a test issue to validate the target system can receive ACC data"

Value: Understand target system structure before migration scripting

Use Case 5: Training & Documentation

Scenario: Training new developers on APS APIs

Interactive Learning:

Trainee: "What data can I get from an issue?"
Copilot: [Shows real issue structure with actual data using getIssueDetailsTool]

Trainee: "How do I create an issue?"
Copilot: [Demonstrates with createIssueTool showing required and optional fields]

Trainee: "How are folders organized?"
Copilot: [Demonstrates with live project data]

Value: Learn with real examples instead of abstract documentation

🔄 Customer Workflow Examples

For Construction Tech Companies:

Morning Standup:
PM: "What's blocking us today?"
Dev: [Opens VS Code] "Show me all high-priority issues"
Result: Team sees real blockers in 5 seconds

During Development:
Dev: "List all .dwg files in the structural folder"
Copilot: [Returns file list]
Dev: Uses list to build file processing automation

Before Deployment:
Dev: "How many projects will this affect?"
Copilot: [Lists all accessible projects]
Dev: Plans rollout strategy

For System Integrators:

Discovery Phase:
"What issue types exist?" → Map to target system
"Show me all custom attributes" → Plan data transformation
"List all projects by region" → Scope integration effort

Development Phase:
"Get sample issue data" → Test transformation logic
"What's the folder structure?" → Plan file sync strategy
"Show project metadata" → Validate connection

Testing Phase:
"Create test issue" → Validate write operations
"Get issue details" → Verify data completeness
"List recent changes" → Verify sync accuracy

📊 ROI & Metrics

Time Savings:

• API exploration: 30-60 min → 2-5 min (90% reduction)
• Data structure discovery: 45 min → 5 min (89% reduction)
• Integration prototyping: 4 hours → 1 hour (75% reduction)

Productivity Gains:

• Developers stay in IDE: 80% less context switching
• Faster debugging: Real-time data access vs manual API calls
• Reduced errors: AI-assisted queries vs manual Postman testing

Business Impact:

• Faster time-to-market for integrations
• Lower training costs for new developers
• Improved developer experience and satisfaction
• Enables rapid prototyping and innovation

🚀 Future Expansion Opportunities

Planned Enhancements:

1. ✅ Issue Creation - Create new issues (IMPLEMENTED)
2. ✅ Issue Details - Get detailed issue information (IMPLEMENTED)
3. ⏳ Issue Updates - Update existing issues (IN PROGRESS)
4. ⏳ Issue Comments - Add comments to issues (IN PROGRESS)
5. ⏳ Issue Attachments - Upload files to issues (IN PROGRESS)
6. 🔜 Advanced Queries: Filter, sort, aggregate data
7. 🔜 Multi-Project Operations: Bulk queries across projects
8. 🔜 File Operations: Upload/download files
9. 🔜 Webhooks Integration: Real-time notifications in IDE
10. 🔜 Cost Management: Query budget and cost data
11. 🔜 Schedule Data: Access project timelines and milestones
12. 🔜 RFI Management: Query and manage RFIs
13. 🔜 Document Management: Search and analyze documents

Extended Use Cases:

• ✅ Issue creation from natural language descriptions
• Automated issue creation from code comments
• Project health dashboards in IDE
• Compliance checking and reporting
• Automated status updates to stakeholders
• Integration testing frameworks
• Detailed issue analysis with comments and attachments

🎓 Getting Started for Customers

For Construction Tech Teams:

1. Set up Secure Service Account (15 min)
2. Configure MCP server in VS Code (5 min)
3. Start querying your projects (immediate)
4. Build on top with custom tools (ongoing)

For Consultants/Freelancers:

1. Use for rapid prototyping (Day 1)
2. Validate customer requirements (Day 2-3)
3. Build production integrations (Week 1+)
4. Deliver faster, more accurate solutions

For Enterprise Teams:

1. Pilot with 2-3 developers (Week 1)
2. Measure time savings and productivity (Week 2-4)
3. Roll out to entire team (Month 2)
4. Expand with custom tools (Ongoing)

💡 Success Stories (Potential)

Example 1: BIM Coordination Company

• Before: 4 hours to explore API and build issue reporter
• After: 1 hour with MCP-assisted development
• Result: 75% time reduction, faster client delivery

Example 2: Construction Software Vendor

• Before: Support team manually checked API responses
• After: Instant troubleshooting with natural language queries
• Result: 60% faster issue resolution

Example 3: Enterprise General Contractor

• Before: Developers built custom API testing tools
• After: Used MCP server for all API exploration
• Result: Eliminated 20 hours/month of tool maintenance

Development

Prerequisites

• Node.js
• APS application (must be of type Server-to-Server)
• Provisioned access to ACC

Setup

Secure Service Account

Our MCP server will need a secure service account and a private key. Instead of implementing the logic in this code sample, we will use https://ssa-manager.autodesk.io:

• Go to https://ssa-manager.autodesk.io, and log in with your APS client ID and secret
• Create a new secure service account using the Create Account With Name: button; don't forget to specify the first name and last name
• Make sure the new account is selected in the Accounts list
• Make note of the serviceAccountId and email values under Account Details
• Create a new private key using the Create Key button; a *.pem file will be automatically downloaded to your machine
• Make sure the new private key is selected in the Keys list
• Make note of the kid value under Key Details

Autodesk Construction Cloud

• Make sure you've provisioned access to ACC for your APS application
• Invite the secure service account (the email value from earlier) as a new member to your selected ACC projects

Server

• Clone this repository
• Install dependencies: yarn install
• Create a .env file in the root folder of this project, and define the following environment variables:
  • APS_CLIENT_ID - your APS application client ID
  • APS_CLIENT_SECRET - your APS application client secret
  • SSA_ID - your service account ID (the serviceAccountId field from earlier)
  • SSA_KEY_ID - your private key ID (the kid field from earlier)
  • SSA_KEY_PATH - full path to your downloaded *.pem file
• The .env file might look something like this:

APS_CLIENT_ID="AhH9..."
APS_CLIENT_SECRET="1FS4..."
SSA_ID="ZCU2TJH5PK8A5KQ9"
SSA_KEY_ID="8a4ee790-3378-44f3-bbab-5acb35ec35ce"
SSA_KEY_PATH="/Users/brozp/aps-mcp-server-nodejs/8a4ee790-3378-44f3-bbab-5acb35ec35ce.pem"

Usage

MCP Inspector

• Run the Model Context Protocol Inspector: npx @modelcontextprotocol/inspector
• Hit Connect to connect to the MCP server

Claude Desktop

• Make sure you have Claude Desktop installed
• Create a Claude Desktop config file if you don't have one yet:
  • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • On Windows: %APPDATA%\Claude\claude_desktop_config.json
• Add this MCP server to the config, using the absolute path of the server.js file on your system, for example:

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

• Restart Claude Desktop and verify the server is running in Settings → Developer:

• Open Claude Desktop, and try some of the following test prompts:
  • What ACC projects do I have access to?
  • Give me a visual dashboard of all issues in project XYZ
  • List all issues in my project
  • Show me the folder structure
  • Get detailed information for issue [issue-id]
  • Create a new issue titled "Test Issue" with status "open"

Example: Visual Dashboard Generation

Claude can create interactive visualizations and dashboards from your ACC data:

The MCP server enables Claude to:

• Query real-time project data from ACC
• Generate visual dashboards with issue statistics
• Create charts showing issues by type, status, and more
• Provide detailed project insights through natural conversation

For more details on how to add MCP servers to Claude Desktop, see the official documentation.

Visual Studio Code & GitHub Copilot

• Make sure you have enabled MCP servers in Visual Studio Code
• Create .vscode/mcp.json file in your workspace, and add the following JSON to it:

{
    "servers": {
        "aps-mcp-server-nodejs": {
            "type": "stdio",
            "command": "node",
            "args": [
                "/path/to/aps-mcp-server-nodejs/server.js"
            ]
        }
    }
}

For more details on how to add MCP servers to Visual Studio Code, see the documentation

Cursor

• Create .cursor/mcp.json file in your workspace, and add the following JSON to it:

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

For more details on how to add MCP servers to Cursor, see the documentation