# [Unofficial] Autodesk Forma Remote MCP Server

A multi-user remote [MCP](https://modelcontextprotocol.io) server exposing **413
Autodesk Construction Cloud / Forma API tools**, with per-user Autodesk sign-in
so each person sees only their own ACC data.

> **Not an Autodesk product.** This is an independent, unofficial project. It is
> not affiliated with, endorsed by, or supported by Autodesk, Inc. "Autodesk",
> "Autodesk Construction Cloud", and "Forma" are trademarks of Autodesk, Inc.,
> used here only to describe what the software connects to. Provided as-is,
> without warranty — see [LICENSE](LICENSE).

## What it does

- **413 ACC/APS tools** — issues, RFIs, submittals, sheets, cost, model
  coordination, takeoff, forms, assets, transmittals, admin, and more
- **Per-user OAuth** — every call goes out as the signed-in user, so ACC
  permissions apply normally and nobody sees anyone else's data
- **In-app sign-in** — the MCP client prompts for Autodesk authorization and
  re-prompts when a token expires; no pasting URLs into chat
- **Fits a client token budget** — a flat tool list is ~80,000 tokens, so tools
  are disclosed progressively: ~30 exposed, all 413 callable
- **Built for concurrent use** — per-user rate limiting, per-user caching,
  jittered backoff on Autodesk 429s

## Quick start

```bash
npm install
cp .env.example .env   # then fill in your APS credentials
npm run preflight      # validates config and verifies credentials with Autodesk
npm start
```

Full setup, including the ACC Custom Integration step that most people miss:
**[docs/DEPLOY.md](docs/DEPLOY.md)**

## Requirements

- Node 22+
- Your own [Autodesk APS](https://aps.autodesk.com) app (Client ID + Secret)
- ACC account-admin rights, to authorise that app against your hub
- A host that can serve HTTPS

## How auth works

The server is an OAuth 2.1 authorization server for MCP clients and an OAuth
client of Autodesk. Clients never see Autodesk credentials.

```
Client ──► /authorize ──► Autodesk sign-in ──► /oauth/callback
       ◄── code ◄──────────────────────────────┘
       ──► /token ──► access token
       ──► /mcp with Authorization: Bearer …
```

Autodesk tokens are keyed by **Autodesk user id**, not by MCP session — some
clients open a fresh session per tool call, so anything keyed on a session
becomes unreachable immediately. Unauthenticated requests return `401` with
`WWW-Authenticate`, which is what triggers the client's in-app sign-in.

## Tool disclosure

| Tier | What |
|---|---|
| 1 | ~30 common tools listed directly — auth, hubs, projects, folders, issues, RFIs, submittals, sheets, users |
| 2 | `search_acc_tools` finds any of the other ~387 by keyword |
| 3 | `describe_acc_tool` returns one schema; `invoke_acc_tool` runs any of the 413 |

`MCP_TOOL_MODE=full` exposes all 413 directly, for clients with a large budget.

## Testing

```bash
npm test
```

88 tests: registry contract over all 413 tools, auth-leg routing, the OAuth
authorization code flow end to end, per-user cache isolation, and backoff.

## Limitations

- Tokens are held in memory: a restart signs everyone out (clients re-prompt
  automatically), and the server must run as a **single instance**
- Autodesk rate limits per *application*, so everyone on one APS app shares a
  quota; the server allocates a fair share per user
- Only the Streamable HTTP transport is supported

## Licence

MIT — see [LICENSE](LICENSE).