Skip to main content

​
Atoti Intelligence SDK

This is part of the Atoti Intelligence SDK offer.
This guide explains how to enable the OAuth 2.1 / PKCE browser-SSO flow on the Atoti MCP server, so MCP clients (Claude Code, Claude Desktop, Cursor, Cline, VS Code’s MCP support, Gemini CLI) can drive authentication against your IdP without users copy-pasting Bearer tokens.

​
What this enables

When this feature is enabled, the MCP server:
  1. Publishes an RFC 9728 Protected Resource Metadata document at /.well-known/oauth-protected-resource. The document tells clients which authorization server(s) to talk to and which scopes to request.
  2. Returns WWW-Authenticate: Bearer realm="mcp", resource_metadata="..." on 401 responses from /mcp/** and /sse, so clients can discover the metadata document on first contact.
Compliant MCP clients then drive the standard OAuth 2.1 authorization code + PKCE flow against the IdP: the client opens the system browser at the IdP authorization endpoint, the user signs in (with MFA, conditional access, whatever the IdP enforces), the IdP redirects back to a loopback URI, and the client swaps the code for an access token. The token is stored in the OS keychain and refreshed silently in the background. Users SSO once in a browser instead of copy-pasting tokens into their MCP client configuration.

​
Prerequisites

  • The Atoti MCP server is already running. See Atoti MCP server setup guide.
  • An OAuth 2.0 authorization server (Okta, Entra ID, Auth0, Keycloak, Cognito, …) is configured to issue access tokens for users who should be able to call MCP endpoints.
  • The Atoti Spring Security stack is already configured to validate the IdP’s JWTs (this is the same setup used by other Bearer-secured Atoti endpoints — no extra steps).

​
Enable the feature

Add the following to your application.yml:
authorization-servers is the only required setting when enabled=true. Startup fails with a clear error if it is left empty.

​
Property reference

​
IdP setup

Concrete steps vary by IdP, but the broad shape is:
  1. Configure your IdP to issue access tokens for the MCP client (Claude Desktop, Claude Code, Cursor, etc.). Most enterprise IdPs require the client to be pre-registered; some support Dynamic Client Registration (RFC 7591).
  2. Set the resource/audience claim on the issued tokens to match atoti.server.endpoint.mcp.oauth2.resource. Atoti’s JWT validator must already trust this audience.
  3. Allow the redirect URI used by your client. Most MCP clients use a random loopback URI such as http://127.0.0.1:<random-port>/callback.

​
Per-client UX

  • Claude Code, Claude Desktop, Cursor, Cline, VS Code MCP, Gemini CLI: detect the WWW-Authenticate header automatically, open the system browser for the PKCE flow, store the resulting access and refresh tokens in the OS keychain, and refresh silently.
  • Older or stdio-only MCP clients: use the mcp-remote bridge — it performs the PKCE dance locally and proxies SSE to the remote MCP server.

​
Reverse-proxy caveats

If the Atoti server sits behind a reverse proxy that rewrites the host or scheme:
  • Either set atoti.server.endpoint.mcp.oauth2.resource explicitly to the public URL of the server, or
  • Enable Spring Boot’s ForwardedHeaderFilter (via server.forward-headers-strategy=framework) so the request-derived URL honours X-Forwarded-*.
Without one of these, the resource field and the resource_metadata= URL in the challenge header will reflect the internal hostname instead of the public one.

​
Limitations and out-of-scope features

In external mode the MCP server is only a resource server — it advertises discovery metadata and validates Bearer tokens, but it does not issue them. The following are therefore out of scope for external mode (they are the IdP’s responsibility):
  • Dynamic Client Registration (RFC 7591). Customers pre-register MCP clients in their IdP, or rely on the IdP’s own DCR support.
  • /.well-known/oauth-authorization-server. That endpoint is served by the IdP.
If you want Atoti itself to handle client registration and serve the authorization-server metadata, use self-issued mode instead — it implements both. The following are not implemented in either mode in this release:
  • Token Exchange (RFC 8693). The MCP server does not exchange tokens for downstream services.
  • Per-error-code WWW-Authenticate parameters (error=invalid_token, etc., per RFC 6750). The v1 challenge contains only realm and resource_metadata.