Descope

Integrate agentgateway with Descope for authentication and identity management

Descope is an authentication and user management platform. agentgateway can validate JWTs issued by Descope to protect your MCP servers.

Why use Descope with agentgateway?

MCP-native OAuth 2.1 compliance - MCP Servers let you protect your MCP gateway with a full OAuth 2.1 compliant provider. CIMD and DCR are both supported as registration methods
Agent Directory - View all of your agentic identities within one centralized IAM platform
Machine-to-machine access - Client credentials flow for agents and backends that need unattended access
Policies - Enforce policy rules for agent access to downstream services, in conjunction with agentgateway authorization rules using JWT roles claims
User consent for agents - Visual consent flows let users explicitly approve which MCP scopes and tools an agent can access

Configuration

Configure agentgateway to validate Descope JWTs:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  port: 3000
  policies:
    cors:
      allowOrigins: ["*"]
      allowHeaders: ["*"]
      exposeHeaders: ["Mcp-Session-Id"]
    mcpAuthentication:
      mode: strict
      issuer: <YOUR_ISSUER_URL>
      audiences: [<YOUR_MCP_SERVER_URL>]
      jwks:
        url: https://api.descope.com/<YOUR_PROJECT_ID>/.well-known/jwks.json
      resourceMetadata:
        resource: <YOUR_MCP_SERVER_URL>
        scopesSupported:
          - read:all
        bearerMethodsSupported:
          - header
  targets:
    - name: everything
      stdio:
        cmd: npx
        args: ["@modelcontextprotocol/server-everything"]

<YOUR_ISSUER_URL>: Copy this from the Connection Information section of your MCP Server configuration in the Descope Console.
<YOUR_PROJECT_ID>: Found in the Descope Console under Project Settings. The JWKS URL always uses the project ID.
<YOUR_MCP_SERVER_URL>: Your MCP server’s public URL, typically ending with /mcp. The audiences value must match the aud claim in Descope-issued tokens, which equals your MCP server’s resource URL.

Descope setup

Create a project in the Descope Console.
Note your Project ID from Project Settings. The project ID is used in your issuer URL and JWKS URL.
Create an MCP Server in the Descope Console to represent your MCP gateway. Set the MCP Server URL to match the public URL agentgateway exposes (typically ending with /mcp), and define the scopes your server enforces. The MCP Server includes a built-in User Consent Flow for interactive, user-delegated access. Customize it under Server Settings if you need a different login or consent experience.
Copy the Issuer URL from the MCP Server Connection Information section. Use this value for mcpAuthentication.issuer in agentgateway.
If you also need machine-to-machine access (for backend agents or automated testing), create a Client manually and enable the Client Credentials grant type. Note the generated Client ID and Client Secret.

Getting a token

How a client gets a token depends on whether it acts for a user or on its own behalf. These are different paths for interactive clients and machine-to-machine.

Interactive clients (user-delegated)

MCP clients like Claude, Cursor, or a custom client you build handle this automatically using the OAuth 2.1 authorization code flow with PKCE: the client discovers your MCP Server’s OAuth endpoints, registers via CIMD or DCR, and redirects the user through Descope’s User Consent Flow to approve scopes. Point the client at your MCP Server URL. No manual token request is needed. See MCP Servers for details.

Machine-to-machine (testing and automated agents)

For backend agents, scripts, or testing without an interactive client, exchange Client credentials directly for a token using the client credentials flow. Set these once, then the commands below are copy-paste runnable:

export DESCOPE_TOKEN_ENDPOINT=<YOUR_TOKEN_ENDPOINT>
export DESCOPE_CLIENT_ID=<YOUR_CLIENT_ID>
export DESCOPE_CLIENT_SECRET=<YOUR_CLIENT_SECRET>
export MCP_SERVER_URL=<YOUR_MCP_SERVER_URL>

DESCOPE_TOKEN_ENDPOINT: Copy from the Connection Information section of your MCP Server configuration.
DESCOPE_CLIENT_ID / DESCOPE_CLIENT_SECRET: From the Client you created with the Client Credentials grant type enabled.
MCP_SERVER_URL: Must match your MCP Server URL so the token’s aud claim targets your server.

curl -X POST "$DESCOPE_TOKEN_ENDPOINT" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=$DESCOPE_CLIENT_ID" \
  -d "client_secret=$DESCOPE_CLIENT_SECRET" \
  -d "scope=openid read:all" \
  -d "resource=$MCP_SERVER_URL"

Copy the access_token from the response, then use it as a bearer token in requests:

export ACCESS_TOKEN=<TOKEN_FROM_PREVIOUS_RESPONSE>

curl "$MCP_SERVER_URL" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{}},"id":1}'

Role-based authorization

You can use authorization with agentgateway based on your existing Descope roles, such as Tenant Admin in the following example:

policies:
  mcpAuthentication:
    mode: strict
    issuer: <YOUR_ISSUER_URL>
    audiences: [<YOUR_MCP_SERVER_URL>]
    jwks:
      url: https://api.descope.com/<YOUR_PROJECT_ID>/.well-known/jwks.json
  authorization:
    rules:
      # Check for a specific Descope role

Checking for a specific Descope role will depend on your Authorization Claims Configuration.

If using the Default Descope JWT, then roles will be found in jwt.tenants["<YOUR TENANT ID>"].roles, otherwise if using No Tenant Reference authorization claim format, then you can expect to find them in jwt.roles.

Learn more

Tailscale Okta

Was this page helpful?