Docs MCP Server

The Descope Docs MCP Server is a hosted MCP server that gives AI agents and MCP clients access to Descope product knowledge. Use it from IDEs, CLIs, or any MCP-compatible client to get answers and search docs without leaving your environment.

Connecting to the server

Add the Descope Docs MCP Server to your MCP client configuration using the URL below. Example:

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

Tools

The server exposes two tools, both read-only and suitable for open-world use.

Ask a question about Descope

Tool name: ask-question-about-descope

Use this tool to ask a question about Descope to an AI support agent that knows the product. Best for:

• Troubleshooting - errors, configuration, integration issues
• Feature capability - what Descope supports and how it works
• Conceptual questions - flows, auth methods, RBAC, MCP, etc.

Be specific and include the minimum context needed for a full answer (e.g. stack, flow type, error message).

Search Descope documentation

Tool name: search-descope-docs

Use this tool to run a semantic search over Descope reference content. Results are excerpts from the documentation site and other public sources (e.g. GitHub). Use the results as references; always review and interpret them in the context of your question.

How the tools are used

You don't need to choose a tool yourself. Your MCP client's LLM will decide which tool (or tools) to call based on your prompt—it may call ask-question-about-descope, search-descope-docs, or both in the same conversation depending on what you ask.

What you can ask

You can use the Docs MCP Server for a wide range of Descope-related questions. Examples:

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?"

How-to and setup

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

Concepts and capabilities

• "What's the difference between project-level and tenant-level roles?"
• "Does Descope support passkeys? How do I enable them?"
• "How does refresh token rotation work and when is the old token invalidated?"

SDK and API

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

MCP and agents

• "How do I secure my MCP server with Descope?"
• "What scopes do I need for tool-level access control?"

Advanced and architectural questions

You can ask multi-part or architectural questions; the agent understands the Descope SDKs and can help you design backend and frontend flows end-to-end. For example:

• "Design my backend: I need session validation on every API route plus role checks so only users with the 'admin' role can access /api/settings. I'm using Next.js App Router and the Node SDK—show middleware and route handlers."
• "Architect the frontend: I want a sign-in page, a protected dashboard that requires authentication, and a separate admin section that also requires the 'admin' role. Use the React SDK and show how to guard routes and conditionally render the admin UI."
• "I'm building a multi-tenant app with Descope. Walk me through tenant resolution (from JWT or subdomain), attaching tenant to the session, and enforcing tenant-scoped role checks in my API."
• "Design end-to-end: Next.js frontend with Descope React SDK (login, session, logout), API routes that validate the Descope session JWT and check a custom role claim, and a few pages that are public vs protected vs admin-only. Include how to pass the session token to the API and how to handle 401s."
• "How do I implement step-up authentication for a sensitive action? I need the user to re-authenticate (e.g. MFA) before allowing access—what flow and SDK calls do I use on the frontend and how do I validate the step-up on the backend?"

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 (e.g. Next.js, React), auth method (e.g. magic link, OAuth), or environment (e.g. serverless) when it matters.
• Paste exact errors - For troubleshooting, include the error message or code snippet so the agent can target the cause.
• One topic per question - Ask one clear question at a time; you can always ask follow-ups.