Configure OAuth 2.1 | Dcipher Analytics Help Center

Dcipher MCP Server uses OAuth 2.1 with PKCE (RFC 7636) as its only authorization mechanism, following the MCP authorization specification. This page explains how the flow works end to end and how a custom MCP client registers itself.

Most people never need this page - Claude Code and Claude Desktop complete this flow automatically once you point them at the server URL. Read on if you're troubleshooting sign-in, or building your own MCP client against Dcipher MCP Server.

How OAuth works with Dcipher MCP Server

Dcipher MCP Server doesn't mint its own tokens - it's a thin OAuth/PKCE layer in front of your existing Dcipher session. The access token your client ends up with is your real Dcipher access token.

Your MCP client calls the server with no token and gets a 401 with a WWW-Authenticate header pointing at the discovery endpoints.
The client reads /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server to find the /authorize and /token endpoints, and confirms PKCE (S256) is required.
Your browser opens /authorize with a client_id, redirect_uri, and code_challenge. The server validates the client and stores a pending record, then redirects you to the Dcipher sign-in page.
You sign in (if you aren't already) and are redirected back to the server.
The server redirects you to a consent screen naming the requesting client (and its logo, if it provided one), with Allow/Deny.
On Allow, the server mints a one-time authorization code bound to your PKCE challenge and redirects back to your client's redirect_uri. On Deny, it redirects back with an access_denied error and no code.
Your client exchanges the code, plus its PKCE verifier, at /token for an access token and a refresh token - these are your real Dcipher tokens, not a separate credential.
Every subsequent call carries Authorization: Bearer <access_token>, forwarded as-is to the Dcipher services behind the server.
When the access token expires, your client calls /token again with grant_type=refresh_token to get a new one - no re-login needed unless the refresh token itself has expired or been revoked.

Client registration: Client ID Metadata Documents (CIMD)

Dcipher MCP Server registers OAuth clients using Client ID Metadata Documents (CIMD), not Dynamic Client Registration (DCR) - DCR is on a deprecation path in the MCP authorization specification. Claude Code and Claude Desktop handle this automatically; you only need this section if you're building a custom MCP client.

Your client_id must be an https:// URL that resolves to a small JSON document:

{
  "client_id": "https://your-app.example.com/mcp-client.json",
  "client_name": "Your App Name",
  "redirect_uris": ["https://your-app.example.com/callback"]
}

Requirements:

The URL must use https://, carry no userinfo or fragment, and not contain ./.. path segments.
The URL must not resolve to a private or link-local address (RFC 1918 ranges, IPv4/IPv6 link-local). A loopback address (localhost, 127.0.0.1) is only accepted outside production, for local development.
redirect_uris must be a non-empty array of strings.
The document must be a public client: it must not declare a client_secret, and it must not declare token_endpoint_auth_method as client_secret_basic, client_secret_post, or client_secret_jwt. Any of these get the request rejected.

The document is fetched with a 5-second timeout, capped at 5 KB, and cached for one hour.

Loopback redirect URIs for CLI clients: native/CLI tools (like Claude Code) redirect to an ephemeral localhost port that can't be known ahead of time (RFC 8252 §7.3). If your metadata document registers a loopback redirect URI (for example http://localhost:0/callback), any port on that same host and path is accepted at request time - you don't need to register every possible port.

Discovery endpoints

Endpoint	Purpose
`GET /.well-known/oauth-protected-resource`	RFC 9728 resource metadata - tells clients this server is the associated authorization server
`GET /.well-known/oauth-authorization-server`	RFC 8414 server metadata - advertises `/authorize`, `/token`, and PKCE S256 support

Configure your MCP client

Compliant clients discover and complete this entire flow automatically once you add the server URL. There's no bearer token to obtain and paste in by hand. Dcipher MCP Server doesn't issue long-lived static tokens for manual configuration; access tokens are short-lived and refreshed automatically by the client.

Token lifetime

Token	Lifetime
Access token	30 minutes
Authorization code	60 seconds, single-use
Pending authorization (time to complete sign-in)	10 minutes
Refresh token	Rotates automatically via `grant_type=refresh_token`

Security best practices

Tokens are never shared between users - each token is bound to the individual who signed in.
Use your MCP client's built-in OAuth support; avoid hardcoding or copying tokens between environments.
If your Dcipher role or permissions change, you may need to reconnect for the client to pick up the new access.

Common authentication issues

Issue	Possible cause	Resolution
Flow doesn't launch	Pop-up blocker or CLI error	Re-run the command, disable pop-up blockers
Redirect fails	Redirect URI not registered in your client's CIMD document	Confirm the exact `redirect_uri` your client sends matches (or is an allowed loopback variant of) one in `redirect_uris`
`invalid_client` at `/authorize`	`client_id` doesn't resolve to a valid, public-client CIMD document	Confirm the document is reachable over HTTPS, under 5 KB, and doesn't declare a `client_secret`
`access_denied` during sign-in	You weren't logged in to Dcipher when the flow reached the callback, or you (or the client) selected Deny on the consent screen	Restart the connection, sign in first, and select Allow
Tool calls fail after you've connected	Your Dcipher project or organization role doesn't permit the action - this is checked per tool call, separately from sign-in	Verify your role with your Dcipher org admin; this is a permissions issue, not a missing OAuth scope (see Authentication and authorization)
No data returned / repeated 401	Access token expired mid-session and wasn't refreshed	Let your client refresh automatically, or disconnect and reconnect