Descope MCP Server

What is Descope MCP Server about?

Descope MCP Server enables Claude Desktop to call Descope's Management APIs, allowing users to search audit logs, retrieve user records, create new users, and invite users without leaving the AI assistant environment.

How to use Descope MCP Server?

1. Install – either via Smithery:

   npx -y @smithery/cli install @descope-sample-apps/descope-mcp-server --client claude
   

   or manually cloning the repo, running npm install and npm run build.
2. Configure Claude Desktop by editing claude_desktop_config.json and adding a mcpServers.descope entry that points to the built index.js and supplies DESCOPE_PROJECT_ID and DESCOPE_MANAGEMENT_KEY.
3. Restart Claude Desktop – the plug‑in icon (🔌) confirms a successful connection.
4. Run the server (choose stdio or SSE):

   npm run start:stdio   # stdio mode
   npm run start:sse     # SSE mode
   

Key Features of Descope MCP Server

• Search Audits – fetch up to 10 recent audit‑log entries.
• Search Users – retrieve up to 10 user records.
• Create User – add a new user to the Descope project.
• Invite User – send an invitation to a new user.
• Dual Transport – supports both stdio and Server‑Sent Events (SSE) for flexible integration with Claude Desktop.
• Zero‑code Setup – install via a single npx command and configure through a JSON file.

Use Cases of Descope MCP Server

• Admin Automation – let Claude automate routine admin tasks like onboarding users or reviewing recent activity.
• Security Auditing – fetch recent audit logs on‑demand during security investigations.
• User Management – create or invite users directly from conversational workflows.
• Rapid Prototyping – developers can experiment with Descope APIs without writing custom client code.

FAQ from Descope MCP Server

Q: Which Node.js version is required? A: Version 18 or later.

Q: Do I need Claude Desktop installed? A: Yes, the server is intended to be used as an MCP server for Claude Desktop.

Q: How are credentials supplied? A: Through environment variables DESCOPE_PROJECT_ID and DESCOPE_MANAGEMENT_KEY defined in the MCP server config.

Q: Can I run the server without building it first? A: You must run npm run build to generate the compiled index.js before starting the server.

Q: What transport should I choose? A: Use stdio for local development; choose SSE when you need a persistent event stream.

Descope MCP Server

Introduction

The Descope Model Context Protocol (MCP) server provides an interface to interact with Descope's Management APIs, enabling the search and retrieval of project-related information.

Available Tools

• search-audits: Retrieves up to 10 audit log entries from your Descope project.
• search-users: Retrieves up to 10 user records from your Descope project.
• create-user: Creates a new user in your Descope project.
• invite-user: Invites a new user to your Descope project.

Requirements

Before proceeding, make sure you have the following:

• Node.js (version 18 or later)
• Claude Desktop installed on your system
• A valid Descope Project ID and Management Key
• Git installed

To confirm your Node.js installation, run:

node --version  # Expected output: v18.0.0 or later

Setup Instructions

Installing via Smithery

To install Descope MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @descope-sample-apps/descope-mcp-server --client claude

Manual Installation

1. Clone the repository:

   git clone https://github.com/descope-sample-apps/descope-mcp-server.git
   cd descope-mcp-server
   

2. Install the necessary dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

1. Configure Claude Desktop to recognize the Descope MCP server

To locate the claude_desktop_config.json file, open the Claude Desktop app and enable Developer Mode from the top-left menu bar.

Once enabled, go to Settings (also in the top-left menu), navigate to the Developer section, and click the Edit Config button to access and edit claude_desktop_config.json.

Alternatively, to open the configuration file via terminal:

On macOS:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

On Windows:

code %APPDATA%\Claude\claude_desktop_config.json

2. Add the Descope server configuration:

{
  "mcpServers": {
    "descope": {
      "command": "node",
      "args": ["/path/to/descope-mcp-server/build/index.js"],
      "env": {
        "DESCOPE_PROJECT_ID": "your-descope-project-id-here",
        "DESCOPE_MANAGEMENT_KEY": "your-descope-management-key-here"
      }
    }
  }
}

Replace your-descope-project-id-here and your-descope-management-key-here with your actual Descope Project ID and Management Key from app.descope.com/settings/project and app.descope.com/settings/company/managementkeys.

3. Restart Claude Desktop

To apply the changes:

1. Fully quit Claude Desktop (ensure it's not just minimized).
2. Relaunch Claude Desktop.
3. Check for the 🔌 icon to confirm the Descope server is connected.

Running the server

First, build the project:

npm run build

1. Running the server on stdio

npm run start:stdio

2. Running the server on SSE

npm run start:sse