APS MCP Auth Examples

Reference implementations of MCP servers that integrate with Autodesk Platform Services, covering every combination of:

• How the server authenticates to APS
  • 2LO - 2-legged OAuth, app-wide
  • 3LO - 3-legged OAuth, per-user
  • PKCE - 3-legged OAuth for public clients, per-user
  • SSA - Secure Service Account, non-human identity
• How MCP clients authenticate to the server
  • not at all (STDIO)
  • via an external identity provider
  • via an OAuth proxy service

All HTTP-based examples target the 2026-07-28 MCP specification revision via the split MCP TypeScript SDK v2 (@modelcontextprotocol/{server,express,node}), which requires MCP servers to act as OAuth 2.1 resource servers backed by a dedicated authorization server, and prefers Client ID Metadata Documents (CIMD) over Dynamic Client Registration for identifying MCP clients.

Every example exposes the same MCP tools, implemented once in shared/ and reused everywhere: list-projects (hubs + projects, via the Data Management API) and list-contents (a project's top-level folders, or a specific folder's contents).

The examples

Folder	MCP-client auth	What it demonstrates
aps-mcp-server-local	none (STDIO)	The simplest possible setup — a locally spawned process, no MCP-layer auth at all.
aps-mcp-server-remote-auth0	External IdP (Auth0)	This server only verifies tokens; Auth0 (or any OIDC/JWKS provider) remains the authorization server. Per-IdP-user APS providers cached in memory.
aps-mcp-server-remote-proxy	Separate OAuth proxy service	Relies on an OAuth proxy in front of APS authentication (simple-oauth-proxy) to generate "MCP tokens", and uses /internal/exchange endpoint to exchange these for "APS tokens".
simple-oauth-proxy	(is the proxy)	The standalone, provider-agnostic OAuth proxy service consumed by aps-mcp-server-remote-proxy, built with Python + FastMCP.
shared	(library)	The four APS auth provider classes, the two MCP tools, and small helpers reused by every example above.

Setup common to every example

1. Register an APS application at https://aps.autodesk.com/myapps (a Traditional Web App if you'll use any 3LO example; a Server-to-Server / API-key style app is enough for 2LO-only use). For SSA, additionally create a Secure Service Account and register its public key — see the SSA guide.
2. npm install at the repo root — this is an npm workspaces project, so one install resolves shared and all four TypeScript servers.
3. Run any TypeScript example with npm start from inside its folder (or npm run start -w <package-name> from the root), after copying its .env.example to .env and filling in the values for your chosen APS_AUTH_MODE.
4. simple-oauth-proxy is a separate Python/FastMCP service — see its own README for setup; it's only needed if you're trying aps-mcp-server-remote-proxy.

A note on scope

These are teaching examples, optimized to be read end-to-end in one sitting. Several corners intentionally cut for brevity are called out in the relevant README (in-memory-only state with no horizontal-scaling story, a simplified CIMD fetch without full SSRF hardening in the OAuth proxy example, etc.). Don't copy the security-relevant bits verbatim into production without reading those notes.

Two more that apply to the shared tools rather than to any one example:

• No pagination. The Data Management API returns hubs, projects and folder contents one page at a time; list-projects and list-contents read only the first page, so a large account silently sees a truncated list. A real implementation follows the links.next cursor until it's absent.
• Unbounded fan-out. list-projects issues one getHubProjects call per hub concurrently. Fine for the handful of hubs a typical account has; with many hubs it will hit APS rate limits, so cap the concurrency.

And three that apply to the auth providers in shared/:

• Token caching is deliberately naive. Each provider holds one access token and re-requests it shortly before expiry. A real provider would key the cache by scope and share one in-flight request between concurrent callers.
• Any refresh failure ends the session. ThreeLeggedAuthProvider treats every failed refresh as "sign in again". In production you'd distinguish a dead grant (HTTP 400 invalid_grant — refresh token expired or revoked) from a transient one, so an APS outage doesn't discard a perfectly good session.
• State is in-memory and per-instance. aps-mcp-server-remote-auth0 keeps its per-user auth providers and pending sign-ins in lru-cache instances rather than plain Maps, so a long-running process doesn't grow without bound — but scaling out still means moving them to a shared store.