Scope

PR 4/4 of the MCP OAuth 2.1 implementation. This wires everything together: the HTTP controller layer, app.ts integration, login redirect handling, and integration tests. After this PR, the feature is functional end-to-end.

Controller layer

Two Express routers with distinct security profiles:

Public router (mounted before authenticate middleware):

Protected router (mounted after authenticate middleware):

The decision endpoint enforces requireCookieAuth (rejects bearer tokens -- consent must come from a browser session) and requireSameOrigin (CSRF protection via Origin header matching against PUBLIC_URL).

CSRF is handled without a traditional token: the signed_params JWT is baked into the form as a <input type="hidden"> by the server when rendering the consent page. It's unforgeable (HMAC-signed), unreadable cross-origin (same-origin policy prevents an attacker from fetching the page), and session-bound. This effectively functions as a synchronizer token CSRF defense while also binding the authorization parameters. requireSameOrigin is a fast-fail layer on top.

CSP form-action is relaxed on the consent page response only to accommodate Chrome's behavior of extending form-action to the redirect chain. Redirect URIs are validated at DCR time so this is safe.

App integration

• app.ts mounts both routers, the mcpOAuthGuard middleware, and the cleanup schedule. Startup validation ensures MCP_OAUTH_ENABLED requires both MCP_ENABLED and SERVE_APP to be true.
• Login forms (login-form.vue, ldap-form.vue, continue-as.vue) use a new navigateAfterLogin utility that detects /mcp-oauth/ in the redirect target and does a full page navigation (window.location.href) instead of router.push(), since the consent page is server-rendered HTML outside the SPA.

Flow

1. MCP client hits /mcp, gets 401 with WWW-Authenticate containing resource_metadata URL
2. Client fetches /.well-known/oauth-protected-resource, discovers the authorization server
3. Client fetches /.well-known/oauth-authorization-server, gets endpoint URLs
4. Client registers via POST /mcp-oauth/register (RFC 7591)
5. Client redirects user to GET /mcp-oauth/authorize with PKCE challenge
6. User sees consent page (or gets redirected to login first), approves
7. 302 redirect back to client with authorization code and iss parameter (RFC 9207)
8. Client exchanges code at POST /mcp-oauth/token with PKCE verifier
9. Client uses access token on /mcp endpoints

Notable behavior changes

• Login redirect -- all three login forms (login-form.vue, ldap-form.vue, continue-as.vue) now use navigateAfterLogin() instead of direct router.push(). For regular redirects this behaves identically. For /mcp-oauth/ redirects, it does window.location.href (full page navigation) because the consent page is server-rendered HTML outside the SPA. No visible change for non-OAuth login flows.
• app.ts -- new middleware and routes are mounted. The mcpOAuthGuard runs after authenticate on every request (but passes through immediately for non-OAuth sessions). The cleanup schedule runs every 15 minutes when MCP_OAUTH_ENABLED=true.
• Consent page checks mcp_enabled project setting -- if an admin disables MCP via project settings, the consent page renders a 403 error instead of letting the user complete the OAuth flow only to get rejected on /mcp.

Potential Risks / Drawbacks

• The consent page is mounted on the public router (before authenticate) because it needs to handle the unauthenticated
  -> login -> return flow itself. Session validation is done manually via cookie check + getAccountabilityForToken.
• navigateAfterLogin uses window.location.href for OAuth redirects, which causes a full page load. This is intentional -- the consent page is not an SPA route.

Tested Scenarios

• Controller: CORS headers, rate limiting, duplicate param rejection, cookie-only auth enforcement, same-origin check, CSP form-action relaxation, OAuth error formatting
• Login redirect: detects OAuth redirect targets, falls back to router.push for regular redirects
• Blackbox integration tests covering the full OAuth flow end-to-end: discovery, DCR, authorization, token exchange, MCP access with OAuth token, token refresh, revocation, code reuse rejection, PKCE enforcement, denial flow, regular session isolation from OAuth routes

Review Notes / Questions

• Discovery endpoints support both /.well-known/oauth-protected-resource and /.well-known/oauth-protected-resource/mcp (path-based insertion per RFC 9728 Section 3).
• The error handler on the public router converts OAuthError instances to { error, error_description } JSON. Non-OAuth errors fall through to the default Directus error handler.

Testing the full OAuth flow

To try this locally with curl (assumes Directus running at http://localhost:8055):

BASE=http://localhost:8055
CALLBACK=http://localhost:8127/callback

# 1. Discover the authorization server
curl -s $BASE/.well-known/oauth-protected-resource/mcp | jq .

# 2. Register a client
CLIENT_ID=$(curl -s -X POST $BASE/mcp-oauth/register \
  -H 'Content-Type: application/json' \
  -d "{\"client_name\":\"test\",\"redirect_uris\":[\"$CALLBACK\"],\"grant_types\":[\"authorization_code\",\"refresh_token\"]}" \
  | jq -r .client_id)
echo "client_id: $CLIENT_ID"

# 3. Generate PKCE challenge
CODE_VERIFIER=$(openssl rand -hex 32)
CODE_CHALLENGE=$(echo -n "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')

# 4. Open the consent page in a browser (log in if prompted, then approve)
open "$BASE/mcp-oauth/authorize?client_id=$CLIENT_ID&redirect_uri=$CALLBACK&response_type=code&code_challenge=$CODE_CHALLENGE&code_challenge_method=S256&scope=mcp:access&resource=$BASE/mcp"
# -> after approval, browser redirects to callback with ?code=... (grab it from the URL bar)

# 5. Paste the code from the redirect URL
AUTH_CODE=<paste code here>

# 6. Exchange the code for tokens
TOKENS=$(curl -s -X POST $BASE/mcp-oauth/token \
  -d "grant_type=authorization_code&client_id=$CLIENT_ID&code=$AUTH_CODE&redirect_uri=$CALLBACK&code_verifier=$CODE_VERIFIER&resource=$BASE/mcp")
echo "$TOKENS" | jq .
ACCESS_TOKEN=$(echo "$TOKENS" | jq -r .access_token)

# 7. Use the access token on /mcp
curl -s $BASE/mcp \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq .

Requires MCP_ENABLED=true and MCP_OAUTH_ENABLED=true.

Connecting Claude

Any MCP client that supports RFC 9728 discovery will handle the OAuth flow automatically -- you just point it at your Directus MCP endpoint.

Claude.ai (web):

1. Go to Settings > Integrations
2. Add a new integration, enter https://your-directus.com/mcp as the server URL
3. Claude discovers the OAuth endpoints, opens a browser tab to your Directus consent page
4. Log in (if not already), approve the connection
5. Done -- Claude can now use your Directus MCP tools

Claude Code (CLI):

claude mcp add --transport mcp directus https://your-directus.com/mcp

This also works with localhost:8055/mcp for Claude Code if you set your PUBLIC_URL correctly.

OpenAI Codex:

Codex's MCP client (pinned to rmcp 0.15.0) doesn't send the RFC 8707 resource parameter (openai/codex#13891). Works out of the box with the default MCP_OAUTH_REQUIRE_RESOURCE=false -- no client-side config needed.

Any other MCP client that supports remote servers with OAuth should work the same way -- the client hits /mcp, gets a 401 with WWW-Authenticate pointing to the discovery metadata, and takes it from there.

Tested with

• Claude Code locally
• Claude
• Claude.ai
• Codex CLI

Checklist

• Added or updated tests
• Documentation PR created here or not required
• OpenAPI package PR created here or not required