APS Auth0 Example

Example MCP server for Autodesk Platform Services demonstrating proper auth implementation.

https://github.com/user-attachments/assets/496794cb-7e3d-496f-8b5e-8604ae866e7a

Auth0 is just one option here. This example uses Auth0 as the Layer 1 authorization server, but nothing about the MCP server is tied to it — the server only verifies bearer tokens against a standard OAuth/JWKS endpoint. You can swap in any OAuth 2.0 authorization server that fits your needs, such as WorkOS, Okta, Microsoft Entra ID, Keycloak, or your own. If you do, adapt auth/auth0.js (token verification and metadata discovery) and the corresponding config accordingly; the Layer 2 APS flow stays the same.

Features

Two-layer authentication, targeting the 2026-07-28 MCP specification release candidate:

• Layer 1 (MCP client -> MCP server): every /mcp request must carry an Authorization: Bearer token issued by Auth0, which acts as the OAuth authorization server for this MCP server. Clients register via a Client ID Metadata Document (CIMD) instead of Dynamic Client Registration — see Setting up Auth0 below.
• Layer 2 (MCP server -> APS): standard APS 3-legged OAuth, run out-of-band in the user's browser. The MCP client's own token is never forwarded to APS (no token passthrough).
• The server is fully stateless — a fresh MCP server instance is built per request (no Mcp-Session-Id), from just the validated Layer-1 subject. Each tool then tries to resolve that user's cached APS token itself.
• When a tool needs the user to sign in, it returns a plain-text login link in the tool result. (URL elicitation, so clients can prompt the user directly, may be reintroduced later.)

What's inside

• app.js: Express app wiring Layer 1 (Auth0 bearer auth + OAuth protected-resource metadata) in front of the stateless MCP handler from mcp.js
• mcp.js: Defines the MCP tools for APS projects and builds the per-request MCP server — a fresh server is built per request from just the caller's user ID. A shared withAuth helper wraps every tool handler: it resolves the caller's APS access token (or returns a login prompt if they haven't signed in yet) before the handler runs, which then calls @aps_sdk/* clients directly with that token
• auth/auth0.js: Layer 1 — verifies Auth0-issued access tokens (OAuthTokenVerifier) and fetches Auth0's OAuth metadata
• auth/aps.js: Layer 2 — APS 3-legged OAuth via @aps_sdk/authentication (authorization URL, code exchange, token refresh, per-user token cache)

This example targets @modelcontextprotocol/server/@modelcontextprotocol/node 2.0.0-beta, which implement the still-unreleased 2026-07-28 spec revision. @modelcontextprotocol/express supplies the Express-specific OAuth resource-server helpers (requireBearerAuth, mcpAuthMetadataRouter) for that same beta line — APIs may still change before the spec and packages are finalized.

Architecture

Two independent OAuth relationships meet at the MCP server. Layer 1 guards the /mcp endpoint itself (MCP client ↔ MCP server, via Auth0). Layer 2 lets the server call APS on the user's behalf (MCP server ↔ APS, standard 3-legged OAuth). The two never mix: the client's Auth0 token is only ever used to identify the caller, and is never forwarded to APS.

flowchart LR
    Client["MCP Client<br/>(OAuth + CIMD)"]

    subgraph Server["MCP Server — Express (app.js)"]
        direction TB
        Bearer["requireBearerAuth<br/>auth0TokenVerifier<br/>(auth/auth0.js)"]
        Handler["createMcpServer(userId)<br/>withAuth → tools<br/>(mcp.js)"]
        Callback["GET /auth/callback<br/>completeLogin<br/>(auth/aps.js)"]
        Cache[("Per-user APS<br/>token cache")]
    end

    Auth0["Auth0<br/>(Layer 1 authorization server)"]

    subgraph APS["Autodesk Platform Services"]
        APSOAuth["3-legged OAuth"]
        DM["Data Management API"]
    end

    Client -->|"1 · Bearer token on /mcp"| Bearer
    Bearer -.->|"verify JWT via JWKS"| Auth0
    Bearer -->|"userId = sub"| Handler
    Handler -->|"resolve cached token"| Cache
    Handler -.->|"no token → return login link"| Client
    Handler ==>|"with token → call API"| DM

    Client -.->|"2 · browser sign-in"| APSOAuth
    APSOAuth -->|"redirect w/ code"| Callback
    Callback -->|"exchange code, cache tokens"| Cache

Authentication flow

The full round trip the first time a user connects and asks a question — the two layers are numbered to match the diagram above.

sequenceDiagram
    autonumber
    participant C as MCP Client
    participant S as MCP Server<br/>(/mcp)
    participant A as Auth0
    participant B as User Browser
    participant P as APS

    rect rgb(235, 244, 255)
    Note over C,A: Layer 1 — MCP client ↔ MCP server
    C->>S: GET /mcp (no token)
    S-->>C: 401 + WWW-Authenticate<br/>(resource metadata URL)
    C->>S: GET /.well-known/oauth-protected-resource/mcp
    S-->>C: metadata → Auth0 is the authorization server
    C->>A: OAuth (CIMD registration, RFC 8707 resource)
    A-->>C: access token (JWT)
    C->>S: /mcp + Bearer <Auth0 JWT>
    S->>S: verify JWT via JWKS → userId = sub
    end

    rect rgb(235, 255, 240)
    Note over S,P: Layer 2 — MCP server ↔ APS (per user, out-of-band)
    S->>S: getValidAccessToken(userId) → none yet
    S-->>C: tool result: "Sign in" link<br/>(buildAuthorizationUrl)
    B->>P: open link, authenticate + consent
    P-->>B: redirect /auth/callback?code&state
    B->>S: GET /auth/callback?code&state
    S->>P: exchange code → APS tokens (completeLogin)
    S->>S: cache tokens under userId
    end

    Note over C,P: Subsequent calls reuse cached tokens
    C->>S: retry /mcp tool call
    S->>P: call Data Management API with APS token
    P-->>S: data
    S-->>C: tool result

Setting up Auth0 (Layer 1)

This protects /mcp itself — separate from, and in addition to, the APS sign-in below.

1. In your Auth0 tenant, create an API (Applications > APIs > Create API) representing this MCP server. Use the server's public /mcp URL — https://<PUBLIC_HOST>/mcp (e.g. https://your-server.example.com/mcp) — as the Identifier. The server derives its Auth0 audience from PUBLIC_HOST, so the Identifier must match exactly.
2. Enable Client ID Metadata Documents so MCP clients (which host their own CIMD instead of registering an app in your tenant) can connect: go to Settings > Advanced, and toggle on Client ID Metadata Document Registration.
3. For MCP-specific resource-parameter handling (RFC 8707), also enable the Resource Parameter Compatibility Profile in the same Settings > Advanced section.
4. Grant the MCP client(s) you intend to use access to the API you created in step 1 (Applications > APIs > your API > Application Access, or authorize the scopes by default for third-party applications in the API's settings).
5. Set AUTH0_DOMAIN (your tenant domain, e.g. your-tenant.us.auth0.com) in .env. The audience is computed from PUBLIC_HOST and does not need to be set separately.

With this in place, MCP clients that support CIMD (per SEP-991) can discover Auth0 via this server's /.well-known/oauth-protected-resource/mcp and authenticate without any manual app registration in your tenant.

Setting up APS 3-legged OAuth (Layer 2)

1. Reuse or create an APS app (Traditional Web App type) at https://aps.autodesk.com/myapps.
2. Add the callback URL https://<PUBLIC_HOST>/auth/callback (the server derives it from PUBLIC_HOST) to the app's allowed callback URLs.
3. Set APS_CLIENT_ID, APS_CLIENT_SECRET, and PUBLIC_HOST in .env.

The per-user APS token cache in auth/aps.js (and the state -> user correlation map used during login) are kept in memory for this example — swap them for Redis (or similar) in production.

Deploy

This server cannot be run locally. Everything (the /mcp URL, the APS callback, and the Auth0 audience) is derived from a single PUBLIC_HOST, and that host must be publicly reachable over HTTPS and registered as the API Identifier ("audience") in Auth0 — see Setting up Auth0. Deploy it to a public host; there is no localhost fallback.

1. Install dependencies: npm install
2. Create a .env in the repo root (see .env for the full list):
   • APS_CLIENT_ID, APS_CLIENT_SECRET (see Setting up APS 3-legged OAuth)
   • AUTH0_DOMAIN (see Setting up Auth0)
   • PUBLIC_HOST — the server's public host (e.g. your-server.example.com, no scheme). The server derives all of the following from it:
     • the public /mcp URL and Auth0 audience: https://<PUBLIC_HOST>/mcp
     • the APS callback URL: https://<PUBLIC_HOST>/auth/callback
     • the host allowlist
   • Optional: PORT (default 3000)
3. Start the server: npm start

Connect an MCP client that supports OAuth (and ideally CIMD + the 2026-07-28 revision) to https://<PUBLIC_HOST>/mcp, and start asking questions such as:

• What projects do I have access to?
• What issues are open in that project?

The first request will prompt you to sign in with your Autodesk account (Layer 2); once that completes, retry the same request.