Discovery Endpoints

Descope hosts a .well-known OpenID Connect discovery endpoint for each MCP server. This endpoint publishes OAuth metadata that MCP clients use to discover authorization endpoints, token endpoints, supported scopes, and other OAuth configuration details.

The discovery endpoint follows the OpenID Connect Discovery specification and includes standard OAuth 2.1 fields, plus MCP-specific extensions.

Discovery Endpoint Structure

The well-known endpoint returns a JSON document containing OAuth configuration metadata. Here's an example structure:

{
  "issuer": "https://api.descope.com/v1/apps/agentic/P32juVkF2iM8wAGoM8PiLkGi6POV/MS35d1Xw1Yo6zozsW7n8BU6xLmnAs",
  "jwks_uri": "https://api.descope.com/P32juVkF2iM8wAGoM8PiLkGi6POV/.well-known/jwks.json",
  "authorization_endpoint": "https://api.descope.com/oauth2/v1/apps/agentic/P32juVkF2iM8wAGoM8PiLkGi6POV/MS35d1Xw1Yo6zozsW7n8BU6xLmnAs/authorize",
  "response_types_supported": [
    "code"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "token_endpoint": "https://api.descope.com/oauth2/v1/apps/agentic/P32juVkF2iM8wAGoM8PiLkGi6POV/MS35d1Xw1Yo6zozsW7n8BU6xLmnAs/token",
  "userinfo_endpoint": "https://api.descope.com/oauth2/v1/apps/P32juVkF2iM8wAGoM8PiLkGi6POV/userinfo",
  "scopes_supported": [
    "mcp:schedule_meetings",
    "mcp:read_hubspot_contacts",
    "mcp:send_confirmation_email",
    "outbound.token.fetch"
  ],
  "claims_supported": [
    "iss",
    "aud",
    "iat",
    "exp",
    "sub",
    "name",
    "email",
    "email_verified",
    "phone_number",
    "phone_number_verified",
    "picture",
    "family_name",
    "given_name"
  ],
  "revocation_endpoint": "https://api.descope.com/oauth2/v1/apps/P32juVkF2iM8wAGoM8PiLkGi6POV/revoke",
  "registration_endpoint": "https://api.descope.com/v1/mgmt/mcp/client/P32juVkF2iM8wAGoM8PiLkGi6POV/MS35d1Xw1Yo6zozsW7n8BU6xLmnAs/register",
  "code_challenge_methods_supported": [
    "S256"
  ],
  "client_id_metadata_document_supported": true
}

Field Descriptions

Standard OAuth Fields

These fields follow the standard OpenID Connect Discovery specification:

Note

The jwks_uri is the same for every MCP server within a Descope project, as the same private key is used to sign all JWTs created within your Descope project.

issuer: The unique identifier for the authorization server. Used to verify tokens and construct other endpoint URLs. The issuer URL is structured as: <Descope Base URL>/v1/apps/agentic/<Project ID>/<MCP Server ID>.

Note

The MCP Server ID is not modifiable once the MCP server is created.

jwks_uri: The URL of the JSON Web Key Set (JWKS) endpoint containing public keys for verifying signed tokens.
authorization_endpoint: The endpoint where clients initiate the authorization flow.
token_endpoint: The endpoint for exchanging authorization codes for access tokens.
userinfo_endpoint: The endpoint for retrieving user information using an access token.
scopes_supported: An array of scopes supported by the MCP server. This list is automatically updated based on the scopes you define in your MCP server configuration.
claims_supported: An array of standard OAuth claims that may be included in tokens. Currently, this list cannot be modified and contains standard OpenID Connect claims such as iss, aud, sub, email, name, etc.
revocation_endpoint: The endpoint for revoking access or refresh tokens.
response_types_supported: Supported OAuth response types (always ["code"] for authorization code flow).
subject_types_supported: Supported subject identifier types (always ["public"]).
id_token_signing_alg_values_supported: Supported JWT signing algorithms (always ["RS256"]).
code_challenge_methods_supported: Supported PKCE code challenge methods (always ["S256"]).

Conditional Fields (Based on MCP Client Registration Configuration)

registration_endpoint: The endpoint for Dynamic Client Registration (DCR). This field is only present when DCR is enabled for the MCP server. If DCR is disabled, this field will not appear in the discovery document.
client_id_metadata_document_supported: A boolean indicating whether Client-Initiated Metadata Discovery (CIMD) is supported. This is true when CIMD is enabled, and false when CIMD is disabled.

OAuth Protected Resource Metadata

Note

The OAuth Protected Resource Metadata must be hosted by the MCP server developer, not by Descope. You'll need to host this JSON document at <MCP Server URL>/.well-known/oauth-protected-metadata on your MCP server.

MCP servers advertise their authorization server using OAuth Protected Resource Metadata. This metadata document is typically returned in the WWW-Authenticate header when an MCP server responds with a 401 Unauthorized error, or can be accessed via a well-known endpoint.

The protected resource metadata document references the Descope well-known discovery endpoint and provides resource-specific information:

{
  "authorization_servers": [
    "https://api.descope.com/v1/apps/agentic/P32juVkF2iM8wAGoM8PiLkGi6POV/MS37k7ewcHY6bDkMEtubEidQ8cvAy"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource": "[YOUR MCP SERVER URL]",
  "resource_documentation": "[YOUR MCP SERVER DOCS URL]",
  "scopes_supported": ["mcp:hubspot","mcp:google-calendar"]
}

Protected Resource Metadata Fields

authorization_servers: An array containing the issuer URL(s) of the authorization server(s) that can issue access tokens for this resource. Each URL in this array should correspond to the issuer field from a well-known discovery document.
bearer_methods_supported: The methods supported for presenting access tokens. Always ["header"] for MCP servers, indicating tokens should be sent in the Authorization: Bearer <token> header.
resource: The URL of the protected resource (your MCP server URL).
resource_documentation: (Optional) A URL pointing to documentation for the protected resource.
scopes_supported: A subset of scopes supported by this resource. This may be a filtered list of the scopes defined in the well-known discovery document's scopes_supported field.

Note

Depending on the MCP client you're using, the scopes_supported field may have to exactly match the scopes you've defined in your MCP server configuration, even though this is not required by the MCP specification.

Relationship to Well-Known Discovery Document

The protected resource metadata document references the well-known discovery endpoint through the authorization_servers field. MCP clients follow this workflow:

Discover the protected resource metadata (via WWW-Authenticate header or well-known endpoint)
Extract the authorization_servers URL(s) from the metadata
Fetch the well-known discovery document from each authorization server URL
Use the discovery document to find OAuth endpoints (authorization_endpoint, token_endpoint, jwks_uri, etc.)
Initiate the OAuth flow using the discovered endpoints

This two-step discovery process allows MCP servers to advertise their authorization server location independently of the detailed OAuth configuration, which is then fetched from the well-known discovery endpoint.

How MCP Clients Use the Discovery Endpoint

MCP clients use the discovery endpoint to:

Discover OAuth endpoints without hardcoding URLs
Understand supported scopes before initiating authorization
Determine if DCR or CIMD is available via the registration_endpoint and client_id_metadata_document_supported fields
Verify token signing keys using the jwks_uri
Understand supported authentication methods and algorithms

Here is a simplified sequence diagram of how MCP clients use the discovery endpoint:

The discovery endpoint enables MCP clients to integrate with your MCP server dynamically, adapting to configuration changes automatically.

Visit our MCP Servers documentation for more information on how to configure your MCP server and get this discovery document for your own server.

Was this helpful?

On this page