- verified: a live sign-in was done and the steps worked.
- documented: the vendor’s own docs describe the setup. The steps have not been run here.
- unverified: no vendor page we read confirms the setup. It comes from the research note only and may be wrong.
auth.mode: jwt, auth.as.enabled: true, auth.resource set to the MCP URL, and auth.as.issuer set to the server’s origin. Dynamic Client Registration is off by default. Opt in with auth.as.dynamicRegistration: true only for a client that needs it. A client that uses only a metadata document does not need it.
Bundled authorization server
Tier 1: metadata document or DCR
Claude Code
/mcp starts the same browser sign-in. If a server needs an exact redirect port, add --callback-port <port>.
The same flow worked against /mcp/essentials. Claude Code used its metadata document and a loopback callback on a dynamically selected port; it did not use DCR.
claude.ai custom connector
Add a custom connector with the MCP URL and sign in. The connector useshttps://claude.ai/oauth/mcp-oauth-client-metadata as its client id and redirects to https://claude.ai/api/mcp/auth_callback; it does not use DCR. The metadata-document flow completed without stalling after metadata was fetched. The same connector worked from Claude Desktop.
ChatGPT (Plugins)
There is no separate developer-mode toggle.- Open
chatgpt.com/plugins, select the plus button, then select Add custom MCP server. - Enter a name and description. Under Connection, enter the MCP URL including
/mcp. - Set Authentication to OAuth, accept I understand and want to continue, then select Create as a plugin.
- Sign in and approve access.
https://chatgpt.com/oauth/client.json as its client id and redirects to https://chatgpt.com/connector_platform_oauth_redirect; it does not use DCR. After a server-side change, use the plugin’s Refresh action to re-read metadata. One plugin is available in chatgpt.com, the ChatGPT desktop app and the desktop app’s Codex view as @<plugin>.
Codex
https://chatgpt.com/oauth/codex/client.json as its client id and redirects to http://127.0.0.1/callback; it does not use DCR. The default registration mode is auto: a metadata document when the server advertises one and the callback is loopback, otherwise DCR. codex mcp add ... --oauth-client-id <id> uses a pre-registered client and skips registration; add that client under auth.as.clients.
In the ChatGPT desktop app, open Settings, select MCP servers, then Add server. Choose Streamable HTTP, enter the MCP URL, leave the bearer-token and header fields empty, restart, then select Authenticate. OAuth is the default when those fields are empty. The desktop app, CLI and IDE extension share ~/.codex/config.toml. Servers configured there are available to Codex sessions in those surfaces, but not to ordinary ChatGPT chats.
Antigravity
In the Antigravity desktop app on Windows, open its MCP settings and add the MCP URL, then sign in. Antigravity useshttps://antigravity.google/oauth/client-metadata.json as its client id and redirects to https://antigravity.google/oauth-callback; it does not use DCR.
Gemini CLI
Gemini CLI registers by DCR, and its page does not mention a metadata document. Setauth.as.dynamicRegistration: true for it. In settings.json:
/mcp auth vault inside the CLI. The research note says Gemini CLI stopped serving personal accounts on 2026-06-18.
Tier 2: DCR or pre-registered only
Grok Build’s add command, from the research note, is
grok mcp add --transport http <name> <url>. VS Code takes the server in .vscode/mcp.json under servers, with "type": "http" and url. Zed takes it under context_servers with url. None of these forms is confirmed by a page we read.
Tier 3: bearer-only APIs
These send a token and run no OAuth flow, and they do not refresh. A token from the bundled server lastsauth.as.accessTokenSeconds (1800 by default), so use a token you mint for the API and keep its lifetime in mind.
Bring your own authorization server
WorkOS AuthKit
Tag: verified. Claude Code and the claude.ai custom connector, also used from Claude Desktop, each completed a live sign-in on 2026-10-12 and ran a read tool successfully. Do not enableauth.as: the bundled server is refused under oidc.
-
Create the default resource indicator through the API. It returns
201:The default applies to clients that omitresource, and only to metadata-document or DCR clients. A wildcard indicator cannot be the default. Changing the default later is dashboard-only (Set as default). Without a default indicator,audis the environment’s client id, and reliquary-tc refuses that token. -
In the dashboard, under Connect and then Configuration, turn on Client ID Metadata Documents (CIMD). It is off by default. Dynamic Client Registration (DCR) is also dashboard-only: turn it on only for a client that needs it. To read the state from outside, AuthKit’s
/.well-known/oauth-authorization-serverhas noregistration_endpointwhile DCR is off. Itstoken_endpoint_auth_methods_supportedlistsnone,client_secret_postandclient_secret_basic. -
AuthKit Connect access tokens carry
org_id, but noroleorpermissionsclaim, even when the organization member has a role. Map the organization id to the scopes its members receive. The example grants read access only; addwrite:*deliberately if every member of that organization should write. Per-role scopes require a WorkOS API lookup, which reliquary-tc does not perform. -
Point reliquary-tc at AuthKit:
issueris the AuthKit domain origin, with no trailing slash, exactly as/.well-known/oauth-authorization-serverstates it.jwksUriishttps://<authkit-domain>/oauth2/jwks.audienceandresourceare both the MCP URL.oidcmode runs discovery at boot and checks the issuer exactly, and it refuses to boot if discovery fails. Do not setauth.scopesSupportedto reliquary-tc scopes for this recipe: Claude Code requests the scopes advertised there, and AuthKit refuses them withinvalid_scope. -
Check Protected Resource Metadata at the path-suffixed URL, which is where reliquary-tc serves it:
Its
authorization_serversnames the AuthKit issuer. -
After changing
claimMapping, clear any stored client authentication and sign in again. A token issued beforeorg_idwas present cannot gain the new mapping; choose the organization during the new sign-in.
Keycloak 26.7
Tag: documented (Keycloak MCP authorization server guide). Measured against Keycloak 26.7.4: a token issued by the realm gotinitialize 200 and tools/list 200, and a request with no token got 401 with resource_metadata. The guide marks both features as experimental, and its header reads “Nightly 26.8.0”, so check the flags against your release.
Known issue, observed 2026-10-12: with --features=cimd,resource-indicators and the client profile and policy below, Keycloak refused an authorization request whose client_id was a metadata-document URL with client_not_found. This happened for Claude Code and a VS Code client id; the client-policy executor did not run. Until that is resolved, the metadata-document path is not usable on this release. This is under investigation; no workaround is documented here.
-
Start Keycloak with the features the guide names, behind a TLS-terminating proxy:
-
Create the client scopes
read:notesandwrite:notesas realm default-optional, so a client has to ask for them. -
Add an audience mapper (
oidc-audience-mapper) to the client scope that carries them: Included Custom Audience is the MCP URL, and Add to access token is on. With CIMD and the resource-indicator allow list set, the executor adds the mapper for you. - Anonymous DCR: in the Trusted Hosts policy, keep the sending-host match off and the client-URI match on. Keycloak refuses both off.
-
CIMD: as the guide describes, create a client profile with the
client-id-metadata-documentexecutor, and a client policy with theclient-id-uricondition (uri-schemehttps,trusted-domains). List each client’s CIMD host intrusted-domains:claude.aifor Claude Code,chatgpt.comfor Codex,vscode.devandzed.dev. Setresource-indicator-allow-listto the MCP URL. On 26.7.4 this configuration still hit the known issue above before the executor ran. -
Point reliquary-tc at the realm:
The token’s
scopeclaim carriesread:notes write:noteswhen a client asks for them. Both names are scopes the server checks, so noscopeMapis needed. The metadata-document login remains blocked by the known issue above.
Cloudflare Access: not yet supported
Cloudflare Access managed OAuth issues opaqueoauth: bearer tokens and checks them at the edge. reliquary-tc verifies JWTs locally and cannot check an opaque token, so this server cannot accept Access tokens. Use the bundled server, WorkOS AuthKit or Keycloak. The Cloudflare workers-oauth-provider library has the same opaque-token limit.
Sources
Vendor pages and live results used for this update were checked on 2026-10-12. Facts marked “research note” are not on the pages we read; they come from the research note of 2026-10-09.- Claude connector authentication: https://claude.com/docs/connectors/building/authentication
- Claude Code MCP: https://code.claude.com/docs/en/mcp
- Codex MCP: https://developers.openai.com/codex/mcp
- ChatGPT Plugins: https://developers.openai.com/plugins/deploy/connect-chatgpt
- Gemini CLI MCP: https://geminicli.com/docs/tools/mcp-server/
- WorkOS AuthKit MCP: https://workos.com/docs/authkit/mcp
- WorkOS AuthKit Connect token claims: https://workos.com/docs/authkit/connect/token-claims
- Keycloak MCP authorization server guide: https://www.keycloak.org/securing-apps/mcp-authz-server
- VS Code MCP servers (read; no OAuth section): https://code.visualstudio.com/docs/copilot/customization/mcp-servers