Client Registration Methods

MCP servers support three client registration mechanisms for onboarding OAuth clients. Each method has different use cases and benefits, and clients supporting all options should follow a specific priority order when choosing which method to use.

Client Registration Approaches

Descope supports three client registration mechanisms for MCP servers:

• Client ID Metadata Documents (CIMD): When client and server have no prior relationship
• Dynamic Client Registration (DCR): For backwards compatibility or specific requirements
• Pre-registration: Pre-defined client in Descope, with it's own unique Client ID and Secret

For new MCP server deployments, Client ID Metadata Documents (CIMD) is the recommended approach as it provides the best balance of security, flexibility, and ease of use for both clients and servers. Pre-registration is ideal for controlled environments with known clients, while DCR should be used primarily for backwards compatibility.

Most MCP servers will want to enable both CIMD and DCR to support the widest range of clients, with CIMD as the primary method and DCR as a fallback option.

Enabling CIMD and DCR

CIMD and DCR are project-level settings. You turn them on once for the project, and every MCP server that uses the project issuer follows them. Both are off by default.

You can find them in the Console under Project Settings > OIDC, in the Client Registration section:

Per-Server Overrides

An MCP server on the project issuer has no CIMD or DCR switch of its own. Its MCP Client Registration section shows how the project registers clients and links to the project settings. If the project has both CIMD and DCR off, clients can't register dynamically with the server.

When CIMD is on for the project, you can turn on Override project settings on an MCP server to set CIMD, its approved domains, and the dynamic registration template for that server only. The override can narrow CIMD but can't widen it. CIMD stays off for the server when the project has it off, and the server only accepts domains that the project's approved domains also cover. DCR and the Client Registration Flow always come from the project.

Client ID Metadata Documents (CIMD)

Client ID Metadata Documents (CIMD) enable clients to use HTTPS URLs as client identifiers, where the URL points to a JSON document containing client metadata.

This approach addresses the common MCP scenario where servers and clients have no pre-existing relationship, making it the recommended method for most MCP deployments.

The following diagram illustrates the complete flow when using CIMD:

To turn CIMD on, see Enabling CIMD and DCR.

When CIMD is enabled, the client_id_metadata_document_supported field in your discovery document will be set to true.

Example Metadata Document

Here's an example of a Client ID Metadata Document, hosted by a client:

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Dynamic Client Registration (DCR)

Dynamic Client Registration (DCR) is the OAuth 2.0 Dynamic Client Registration Protocol (RFC 7591) that allows MCP clients to obtain OAuth client IDs programmatically without user interaction. This option is included primarily for backwards compatibility with earlier versions of the MCP authorization spec.

When to Use DCR

DCR is best suited for:

• Legacy clients: Supporting clients that don't support CIMD
• Fallback option: As a fallback when CIMD is not available
• Specific requirements: When programmatic registration is required but CIMD isn't feasible

However, compared to CIMD, DCR also has some strong limitations. Most notably:

• Server-side management overhead: Each registration creates a new client in Descope, resulting in many clients that need to be managed over time.
• Less flexible: Clients must go through a registration step before they can authenticate

Discovery

Authorization servers advertise support for Dynamic Client Registration by including a registration_endpoint in their OAuth Authorization Server metadata:

For an MCP server on the project issuer, the endpoint is the project's registration endpoint:

{
  "registration_endpoint": "__BaseURL__/v1/mgmt/inboundapp/app/__ProjectID__/register"
}

A server on the MCP Server Issuer advertises its own endpoint instead, such as __BaseURL__/v1/mgmt/mcp/client/P32juVkF2iM8wAGoM8PiLkGi6POV/MS35d1Xw1Yo6zozsW7n8BU6xLmnAs/register.

When DCR is enabled, this endpoint appears in your MCP server's discovery document. If DCR is disabled, registration_endpoint is omitted.

To turn DCR on, see Enabling CIMD and DCR.

The /register Endpoint

When DCR is enabled, clients register by sending a POST request to the registration_endpoint from discovery (the path ends in /register).

Required Parameters

• client_name (string): The name of the client application
• redirect_uris (array of strings): Array of redirect URIs the client will use. Must contain at least one valid URL.

Optional Parameters

• client_uri (string): URL of the client's home page
• logo_uri (string): URL of the client's logo
• logo_content (string): Base64-encoded logo content
• scope (string): Space-separated list of requested scopes (must be from the MCP server's approved scopes)
• description (string): Description of the client application
• token_endpoint_auth_method (string): Authentication method for the token endpoint
• grant_types (array of strings): Array of grant types the client will use
• response_types (array of strings): Array of response types the client will use

Example Registration Request

{
  "client_name": "My MCP Client",
  "redirect_uris": ["cursor://anysphere.cursor-retrieval/oauth/myserver/callback"],
  "scope": "mcp:tools:read mcp:tools:write",
  "client_uri": "https://myclient.com",
  "logo_uri": "https://myclient.com/logo.png",
  "description": "A client application for MCP server integration",
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code"],
  "response_types": ["code"]
}

Registration Response

Upon successful registration, the endpoint returns:

{
  "client_id": "generated_client_id",
  "client_secret": "generated_client_secret",
  "client_id_issued_at": 1640995200,
  "client_secret_expires_at": 0,
  "redirect_uris": ["cursor://anysphere.cursor-retrieval/oauth/myserver/callback"],
  "scope": "mcp:tools:read mcp:tools:write",
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Registration Validation

The /register endpoint validates requests against your MCP server configuration:

• redirect_uris: Must contain at least one valid URL. If the MCP server has approved callback URL patterns (see below), each redirect URI must match one of them.
• scope: Must be from the MCP server's approved scopes list
• client_name: Must be provided and non-empty

If validation fails, the endpoint returns an error response describing what needs to be corrected.

On the project issuer, a client that registers through DCR isn't tied to one MCP server. Descope resolves the MCP server from the resource parameter when the client calls /authorize, and applies that server's scopes there.

You can restrict which clients may register by setting approved callback URL patterns (including wildcards). For example, to allow Cursor MCP clients:

cursor://anysphere.cursor-retrieval/oauth/*/callback

Here * matches the client-specific portion of the redirect URL (for Cursor, the mcpServer name in mcp.json).

After registration, clients typically continue through the Client Registration Flow and end users through the User Consent Flow.

Pre-registration

Pre-registration involves manually registering clients with the authorization server before they can connect. This method is suitable when you have an existing relationship with the client and want to maintain explicit control over which clients can access your MCP server.

When to Use Pre-registration

Pre-registration is best suited for:

• Known clients: When you have a pre-existing relationship with the client (e.g., internal tools, partner integrations)
• Simplified client setup: When clients prefer not to host metadata documents
• Static deployments: When client configurations rarely change

In Descope, you can pre-register clients on the Clients page after the MCP server configuration is saved.