Descope MCP Server

The Descope MCP Server lets you manage your Descope project from any MCP-compatible AI assistant. Ask your assistant to search users, configure flows, inspect audit logs, manage tenants, and more — without leaving your IDE or chat interface. Documentation search and Q&A are built in.

Connecting

{
  "mcpServers": {
    "descope": {
      "url": "https://mcp.descope.com"
    }
  }
}

{
  "servers": {
    "descope": {
      "type": "http",
      "url": "https://mcp.descope.com"
    }
  }
}

claude mcp add --transport http descope https://mcp.descope.com

codex mcp add descope --url https://mcp.descope.com

codex mcp list

[mcp_servers.descope]
url = "https://mcp.descope.com"

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "descope": {
      "type": "remote",
      "url": "https://mcp.descope.com",
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "descope": {
      "serverUrl": "https://mcp.descope.com"
    }
  }
}

Once connected, the server discovers your available Descope projects and prompts you to select one. You can switch projects at any time — just ask your assistant to select a different project.

Security Model

Sessions start in read-only mode. Searching users, listing tenants, inspecting flows, and querying audit logs are all available immediately.

Write operations require explicit elevation. Ask your assistant to elevate the session when you want to make changes. The write window is time-bounded and closes automatically, returning the session to read-only mode.

This means an AI assistant browsing your project cannot make changes unless you explicitly grant it the ability to do so for that session.

What You Can Do

The server covers the full Descope Management API: users, tenants, flows, access control, connections, audit logs, auth keys, and more. Use natural language — you don't need to know specific operation names.

Example Prompts

Users and tenants

• "List all users in the engineering tenant"
• "What SSO connections are configured for tenant acme-corp?"
• "Show me all users who haven't logged in for 30 days"

Flows and configuration

• "What flows do I have configured and which one is the default sign-in flow?"
• "Show me the current FGA schema"
• "What access keys exist in this project and when do they expire?"

Audit

• "Show me the audit log for the last 24 hours filtered by login events"
• "Were there any failed authentication attempts in the last hour?"

Write operations (require elevation)

• "Create a test user with email test@example.com"
• "Add the 'admin' role to user alice@example.com in the acme-corp tenant"
• "Update the default session duration for this project"

Documentation Tools

The server includes two tools for Descope product knowledge:

docs_search — semantic search over Descope documentation and SDK references. Good for finding reference content, configuration details, and code examples.

docs_ask_question — ask a natural language question about Descope and receive a grounded answer. Good for troubleshooting, conceptual questions, and understanding what Descope supports.

Your assistant picks the right tool based on what you ask. You can mix project management and documentation questions in the same conversation.

What You Can Ask

Troubleshooting

• "Why am I getting 'Invalid session token' when validating a JWT in my API?"
• "Magic link sign-in works in dev but fails in production — what should I check?"
• "How do I fix CORS errors when embedding the Descope flow?"

Setup and configuration

• "How do I add Google OAuth to my Descope flow?"
• "How do I map SSO groups to Descope roles?"
• "What are the steps to configure an MCP server in Descope?"

SDK and API

• "How do I get the session token in the React SDK?"
• "How do I validate a Descope JWT in a Lambda authorizer?"
• "What's the Management API call to create a user?"

Architecture

• "Design my backend: session validation on every API route plus role checks so only admins can access /api/settings. I'm using Next.js App Router and the Node SDK."
• "I'm building a multi-tenant app. Walk me through tenant resolution, attaching tenant to the session, and enforcing tenant-scoped role checks in my API."
• "How do I implement step-up authentication for a sensitive action?"

Tips for Better Results

• Be specific — "How do I validate a JWT in AWS API Gateway?" is better than "How do I validate JWTs?"
• Include context — mention your framework (Next.js, React, Python), auth method (magic link, OAuth, SSO), or environment (serverless, edge) when relevant
• Paste exact errors — for troubleshooting, include the error message or code snippet
• One topic per question — ask one clear question at a time; follow-ups work well