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.

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 enable CIMD for your MCP server, see the MCP Server documentation.

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:

{
  "registration_endpoint": "__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 for the MCP server, registration_endpoint is omitted.

Enable DCR under MCP Client Registration in the MCP server settings.

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 defines approved callback URLs (approvedCallbackUrls), each redirect URI must match an approved pattern.
• 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.

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.