MCP Servers

MCP servers are OAuth 2.1 compliant resource servers in Descope, each acting as an independent OAuth provider.

Why Define MCP Servers in Descope

When you define your MCP server in Descope, you're leveraging Descope as your authorization server while your actual MCP server implementation acts as the resource server. This separation provides several key benefits:

No OAuth Infrastructure to Maintain: Descope handles all OAuth 2.1 complexity—token issuance, validation, refresh tokens, client registration, and discovery endpoints—so you can focus on building your MCP tools
Enterprise-Grade Authentication: Use Descope's built-in SSO, MFA, passwordless authentication, and user management without custom integration work
Centralized Access Control: Define policies that govern which clients, users, or agents can access specific MCP tools based on scopes, roles, permissions, or custom attributes
Secure Credential Management: Store and retrieve third-party OAuth tokens and API keys through Connections without hardcoding secrets in your MCP server
Audit and Compliance: Track all authentication events, token issuances, and tool access through Descope's audit logs

You can learn more about how Descope works with MCP, in our MCP use case documentation.

Resource Server vs Authorization Server

In OAuth 2.1 terminology:

Authorization Server (Descope): Issues access tokens, validates client credentials, handles user authentication and consent, and manages client registration. Descope publishes discovery endpoints (.well-known) that expose OAuth metadata, token endpoints, and JWK signing keys.
Resource Server (Your MCP Server): Validates access tokens, checks scopes and audience claims, and enforces authorization before executing MCP tools. Your MCP server receives tokens from clients and validates them using Descope's public JWK keys.

When you configure an MCP server in Descope, you're registering your resource server with Descope's authorization server. Descope then issues tokens with the aud (audience) claim set to your MCP server URL, ensuring tokens can only be used with your specific resource server.

You can create unlimited MCP servers per Descope project and are expected to isolate environments across separate Descope projects (dev, staging, prod).

Settings

See the MCP Server Settings documentation for details on configuring your MCP server, including server details, client registration, scopes, and consent/assessment flows.

Usage Samples

Under the usage samples section, you can find code examples of how to configure your MCP server to use Descope authentication. You will also find your Discovery URL (.well-known) as well as your Issuer URL.

For starter templates for how to get started with MCP Auth with Descope, you can visit our AI examples repository.

OAuth Protected Metadata Resource

You will need to host the OAuth Protected Metadata Resource at the following URL: <MCP Server URL>/.well-known/oauth-protected-metadata. This is the URL that will be used by MCP clients to discover the authorization server endpoints, token endpoints, and supported scopes.

Here is an example of the JSON you will need to host:

{
  "authorization_servers": [
    "https://api.descope.com/v1/apps/agentic/P32juVkF2iM8wAGoM8PiLkGi6POV/MS37k7ewcHY6bDkMEtubEidQ8cvAy"
  ],
  "bearer_methods_supported": [
    "header"
  ],
  "resource": "https://differentially-unmurmurous-lamonica.ngrok-free.dev/mcp",
  "resource_documentation": "https://differentially-unmurmurous-lamonica.ngrok-free.dev/docs",
  "scopes_supported": ["mcp:hubspot","mcp:google-calendar"]
}

Once you've hosted the JSON, try connecting to your MCP server using a client like MCP Inspector to validate that you can complete the OAuth discovery and login process.

How MCP Server authentication works

After you've configured your MCP server settings, MCP clients can discover and connect to your server. The authentication and authorization flow consists of the following steps:

Authorization Server Discovery
Client Authentication
Token Validation & Tool Execution

Authorization Server Discovery

Descope hosts the authorization server and publishes a .well-known metadata document that contains the OAuth endpoints and supported scopes for your MCP server.

The MCP client/server discovery process exposes the authorization URL, token exchange endpoint, and JWK signing keys so MCP clients can authenticate and request scopes without you maintaining OAuth infrastructure.

MCP clients discover these endpoints by first checking the WWW-Authenticate header returned in a 401 Unauthorized response. If the header is not present, the client falls back to requesting well-known metadata URIs.

To learn more about how MCP clients use the discovery endpoint, you can read more about the authorization server discovery process.

Client Authentication

Note

This section applies only to authentication flows with user interaction (authorization code flow). For machine-to-machine (M2M) authentication using the client_credentials flow, user consent and authentication is not required.

When a client makes an /authorize request, Descope runs a User Consent Flow to authenticate the user and collect scope approval.

The consent screen displays the descriptions you configured for each MCP scope, helping users understand what access they are granting.

After consent, Descope issues an access token containing only approved scopes and binds it to the MCP server using the aud claim (set to the MCP Server URL). This prevents tokens from being reused on other MCP servers.

Token Validation & Tool Execution

Your MCP server validates Descope access tokens using the public key from the JWKs endpoint (our session validation functions make this easy).

After validation, the server checks the aud claim and confirms the correct tool scope is present before executing the requested tool.

If the tool needs third-party credentials, the server retrieves them from Connections, Descope's secure token vault, and may exchange the Descope access token or use a Management Key to retrieve the external service token before tool execution.

Clicking the three dots menu to the right of a client and selecting Delete
Selecting multiple clients and clicking the Delete button in the top right corner

When you delete a client, Descope will prompt you for confirmation. Once a client is deleted, the client ID and secret are no longer valid for this MCP server.

Client Details

Clicking on a specific client displays detailed configuration information:

Client Configuration:

Name: Modifiable name that originates from the DCR or CIMD configuration
Client ID and Client Secret: System-generated and not modifiable
Scopes: The scopes allowed for this client on this MCP server
- Mandatory scopes cannot be removed from the client
- Only optional scopes can be modified or removed
Approved Redirect URIs: Client-specific redirect URIs automatically populated from CIMD or DCR registration requests
Tags: Client tags that can be set manually from the console for use in policies

Was this helpful?