io.scanbimlabs/scanbim-mcp

upload_model

Ingest a 3D model from a public URL into APS OSS and kick off a Model Derivative translation job, returning the URN plus a browser viewer link and QR code. Supports 50+ formats: Revit (.rvt/.rfa), Navisworks (.nwd/.nwc), IFC, FBX, OBJ, SolidWorks, point clouds (E57/LAS/RCP), CAD (DWG/STEP/IGES), etc. When to use: you have a publicly downloadable 3D file (S3 presigned URL, GitHub raw, etc.) and need it translated to SVF2 so it can be viewed, measured, or clash-checked via other tools. When NOT to use: the file is only on a local disk or behind auth (fetch will fail) — first push it to a public URL. Do not call to re-translate a model already uploaded; call get_model_metadata instead. APS scopes: data:read data:write data:create bucket:read bucket:create viewables:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 source file_url not reachable or bucket not found — check the ID; 409 bucket name conflict (bucket already owned by another app — pick a unique bucketKey); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Creates the scanbim-models bucket if absent, uploads a new OSS object with a timestamped key (each call creates a distinct object even for the same input), submits a Model Derivative job (x-ads-force=true overwrites prior derivatives for the same URN), and inserts a row into D1 usage_log + models table.

detect_clashes

Run a VDC-grade clash detection pass between two element categories in a translated model, returning each overlapping element pair with a severity (critical/warning), a trade-specific suggested fix, and an estimated rework hour count. Uses AABB bounding-box intersection on elements pulled from the APS Model Derivative properties endpoint, with a synthetic fallback if properties have not yet been computed. When to use: you want a first-pass coordination report between two MEP or structural trades (e.g. Ducts vs Structural Framing) for a model that has finished translating. When NOT to use: the model has not finished translating yet (call get_model_metadata first to confirm manifest.status=='success'), or you need clash detection between more than two categories — call this tool multiple times. APS scopes: data:read viewables:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 URN not found or has no derivatives yet — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY on APS. Inserts a row into D1 usage_log for analytics. Idempotent — repeated calls return the same clash set for a given model.

get_viewer_link

Return a shareable browser URL for the embedded APS viewer and a matching QR code for mobile/XR handoff. Does not require the model to be fully translated — the viewer page will poll the manifest. When to use: you need to hand a stakeholder a URL to see the 3D model in a browser, or print a QR for a jobsite. When NOT to use: you need the raw APS URN for programmatic API calls — use the model_id you already have instead. Do not use to check translation progress — call get_model_metadata. APS scopes: none (URL assembly only); the viewer page itself uses viewables:read data:read server-side via /token. Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (only relevant when the viewer page loads); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY and pure. Idempotent: same model_id always returns the same URL + QR.

list_models

List every object currently stored in the scanbim-models OSS bucket, with URN, size in MB, and a viewer URL for each. Returns the raw OSS inventory, not the D1 models table, so freshly uploaded items appear immediately. When to use: you need to enumerate previously uploaded models to find a URN, show an inventory, or pick one for a follow-up tool call. When NOT to use: you already know the exact URN — call get_model_metadata directly. This tool is not a search; it returns up to the OSS default page (typically first 10 objects unless OSS paginates). APS scopes: bucket:read data:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 bucket not found — no models have been uploaded yet (upload one first); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Idempotent.

get_model_metadata

Fetch the APS Model Derivative manifest and metadata for a URN, including translation progress, derivative outputs, and a viewer URL. Use this to confirm a model has finished translating (manifest.status == 'success') before calling detect_clashes or opening the viewer. When to use: right after upload_model to poll translation progress, or later to inspect which viewable derivatives (SVF2, thumbnail, OBJ) are available. When NOT to use: you just want a link to share — call get_viewer_link. You want the actual element properties list — this tool returns the metadata index, not the full property collection. APS scopes: data:read viewables:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 URN not found or job not yet submitted — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY on APS. Inserts a row into D1 usage_log. Idempotent.

get_supported_formats

Return the full matrix of supported input formats organized by subscription tier (free / pro / enterprise). Use to tell a user whether their file type is accepted before calling upload_model, or to surface pricing tier info. When to use: you need to validate a file extension or show a customer the supported format list. When NOT to use: you already know the extension is common (.rvt/.ifc/.nwd/.obj) — just call upload_model, which returns an 'Unsupported format' error for anything outside the matrix. APS scopes: none (static data). Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (not applicable: no APS call); 403 scope or resource permission denied (not applicable); 404 not applicable; 429 rate limited — backoff and retry (worker-level only); 5xx APS upstream outage — retry with jitter (not applicable). Side effects: READ-ONLY and pure. Idempotent.

No parameters.

acc_list_projects

List every Autodesk Construction Cloud (ACC) / BIM 360 project the configured APS 2-legged app has access to, flattened across all hubs, with hub_id, hub_name, project_id, project_name, and project type. When to use: you need a project_id to pass into acc_create_issue, acc_list_issues, acc_create_rfi, acc_list_rfis, acc_search_documents, or acc_project_summary. When NOT to use: you already have the b.xxxx project_id. This tool makes N+1 API calls (one per hub) so avoid calling it in tight loops. APS scopes: data:read account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied (app not provisioned for any hub in ACC Account Admin → Custom Integrations); 404 no hubs found — check APS app provisioning; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.

No parameters.

acc_create_issue

Create a real issue (punchlist/QC item) in ACC Build's Issues module via the APS Construction Issues v1 API. Returns the ACC-generated issue_id which can be linked back to a model URN or a detected clash. When to use: detect_clashes flagged a critical clash, or a field user reports a QC defect, and you want to track it in ACC for assignment and closeout. When NOT to use: you want to file a formal information request between trades — use acc_create_rfi instead. You want a note on a model element — that is a markup, not an issue. APS scopes: data:read data:write account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied (app not provisioned for the project's ACC account); 404 project_id not found — check the ID (strip any leading 'b.'); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Creates a new ACC issue each call (repeated calls create duplicates). Inserts a row into D1 usage_log.

acc_create_rfi

Create a Request For Information in ACC Build's RFIs module via the APS Construction RFIs v1 API, in 'draft' status. Returns the ACC rfi_id. When to use: a trade or subcontractor needs formal information from the design team (unclear detail, conflicting spec, missing dimension) and you want a tracked paper trail. When NOT to use: the item is just a punchlist fix — use acc_create_issue. The question is internal to one trade — handle inside that trade's toolchain. APS scopes: data:read data:write account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied (app not provisioned for the project's ACC account, or RFIs module not enabled); 404 project_id not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Creates a new draft RFI each call. Inserts a row into D1 usage_log.

acc_list_issues

List up to 50 issues from an ACC project, optionally filtered by status and priority. Returns a normalized array of {id, title, status, priority, due_date}. When to use: you need a dashboard view of open issues, to find a specific issue by metadata, or to check the status of previously created issues. When NOT to use: you want the full audit trail of a single issue — the ACC Issues UI or the per-issue endpoint is better. This tool caps at 50 results and does no pagination. APS scopes: data:read account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 project_id not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.

acc_list_rfis

List up to 50 RFIs from an ACC project, optionally filtered by status. Returns a normalized array of {id, subject, status}. When to use: you need a quick rollup of outstanding or answered RFIs on a project, or to find a specific RFI id. When NOT to use: you want the full response thread of a single RFI — use the ACC UI or per-RFI endpoint. This tool caps at 50 results and does no pagination. APS scopes: data:read account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied (RFIs module may not be enabled on the project); 404 project_id not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.

acc_search_documents

Full-text search the ACC Docs module on a project for drawings, specs, submittals, and other documents matching a query string. Calls the APS Data Management v1 search endpoint scoped to a project. When to use: an agent needs to locate a spec section, a sheet, or a submittal by keyword (e.g. 'fireproofing', 'A-101', 'RFI 23'). When NOT to use: you already have the document URN/lineage — fetch it directly. You want the file contents — this returns metadata; download separately via Data Management. APS scopes: data:read account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied (Docs module access required); 404 project_id not found — check the ID (note: this endpoint re-prepends 'b.' so pass the UUID form); 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.

acc_project_summary

Fetch a single ACC/BIM 360 project's full attributes (name, type, dates, address, hub) from the APS Data Management project endpoint. If hub_id is omitted, the first hub the app can see is used. When to use: you need name, type, or scope details for a single project before acting on it, or to confirm the project still exists. When NOT to use: you want the list of all projects — call acc_list_projects. You want issues/RFIs counts — call the list tools. APS scopes: data:read account:read Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh; 403 scope or resource permission denied; 404 project_id or hub_id not found — check the IDs; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: READ-ONLY. Inserts a row into D1 usage_log. Idempotent.

xr_launch_vr_session

Create a shareable WebXR VR walkthrough session URL (and Meta Quest oculus:// deep link + QR code) for a translated model. The session_id is generated server-side; rendering happens in the user's Quest browser. When to use: you need to walk a client or field team through a model in immersive VR on Meta Quest 2/3/Pro. When NOT to use: the user is on a phone/tablet without a headset — use xr_launch_ar_session or get_viewer_link. The model has not finished translating — call get_model_metadata first. APS scopes: viewables:read data:read (enforced at viewer page load, not at tool call). Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (only at viewer page load); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new session_id (vr_<epoch_ms>). Inserts a row into D1 usage_log which is later read by xr_list_sessions. No APS resources are created.

xr_launch_ar_session

Create a shareable WebXR AR passthrough session URL and QR code. On phone or tablet with WebXR AR support, the model is overlaid on the camera feed at the requested scale. When to use: a field user needs to walk the jobsite with a phone and see the model overlaid in-place at 1:1 scale, or drop a tabletop mini-model on a desk. When NOT to use: the target device is a Meta Quest in VR mode — use xr_launch_vr_session. The device lacks WebXR AR (desktop browser) — use get_viewer_link. APS scopes: viewables:read data:read (enforced at viewer page load, not at tool call). Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (only at viewer page load); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new session_id (ar_<epoch_ms>). Inserts a row into D1 usage_log read by xr_list_sessions. No APS resources are created.

xr_list_sessions

List the last 20 VR/AR sessions launched via xr_launch_vr_session and xr_launch_ar_session, sorted by creation time desc. Sourced from the D1 usage_log table; returns an empty array if D1 is unavailable or no sessions have been recorded. When to use: you want to audit who launched which XR session and when, or surface recent sessions to a user. When NOT to use: you want details (join URL, features) for a specific session — those details live inside the original launch response and are not stored beyond the log row. APS scopes: none (D1 read only). Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (not applicable: no APS call); 403 scope or resource permission denied (not applicable); 404 not applicable; 429 rate limited — backoff and retry (worker-level only); 5xx APS upstream outage — retry with jitter (not applicable). Side effects: READ-ONLY. Idempotent.

twinmotion_render

Queue a photorealistic Twinmotion-style still render of a translated model with time-of-day, weather, season, and resolution controls. Returns a render_id and preview_url; the actual render pipeline is a ScanBIM roadmap item (Week 5 buildout), so today this tool responds synchronously with a stub job descriptor. When to use: you want a scripted way to request a hero still for a proposal or client deck. When NOT to use: you need real-time interactive rendering — use get_viewer_link. You need a moving camera — use twinmotion_walkthrough. You expect the image file bytes back in the response — this tool returns a URL, not bytes. APS scopes: none today (render pipeline is ScanBIM-internal); viewables:read data:read will apply when the pipeline goes live. Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (will apply when pipeline is live); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new render_id (tm_<epoch_ms>). Inserts a row into D1 usage_log. When the pipeline is live it will create a rendering job on ScanBIM's compute backend.

twinmotion_walkthrough

Queue a cinematic Twinmotion-style fly-through video of a translated model. Returns a video_id and download_url; the render pipeline is a ScanBIM roadmap item so today this tool responds synchronously with a stub job descriptor. When to use: you want a short marketing or pre-con video scripted from an agent workflow. When NOT to use: you want real-time interactivity — use get_viewer_link. You want a still image — use twinmotion_render. APS scopes: none today (render pipeline is ScanBIM-internal); viewables:read data:read will apply when live. Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (will apply when pipeline is live); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new video_id (tmv_<epoch_ms>). Inserts a row into D1 usage_log.

lumion_render

Queue a Lumion-style architectural visualization still render with landscaping, people, vehicles, and atmospheric effects. Returns a render_id and preview_url; the render pipeline is a ScanBIM roadmap item so today this tool responds synchronously with a stub job descriptor. When to use: you want a more 'Lumion-flavored' render (lush entourage, vehicles, people) vs. Twinmotion's cleaner look. When NOT to use: you need real-time viewing — use get_viewer_link. You need video — use twinmotion_walkthrough. APS scopes: none today (render pipeline is ScanBIM-internal); viewables:read data:read will apply when live. Rate limits: APS default ~50 req/min per app per endpoint; Model Derivative translation jobs ~60 req/min; OSS uploads size-limited per file to 100MB for direct upload, larger via resumable. Errors: 401 APS token expired/invalid — refresh (will apply when pipeline is live); 403 scope or resource permission denied; 404 URN not found — check the ID; 429 rate limited — backoff and retry; 5xx APS upstream outage — retry with jitter. Side effects: NON-IDEMPOTENT. Each call mints a new render_id (lum_<epoch_ms>). Inserts a row into D1 usage_log.