Descope MCP Server: Audit Logs, User Management

Overview

The Descope MCP Server is a lightweight backend that centralizes audit logs, activity search, and basic user administration for applications using Descope authentication. It captures authentication and event data, indexes it for fast search, and exposes secure endpoints that let administrators inspect activity, manage users, and generate audit trails. The server is intended to be run alongside your application or as a managed service component in environments that require visibility and control over authentication-related events.

This server is useful for teams that need to meet compliance or security requirements, investigate incidents, or provide customer support with detailed activity history. By combining structured audit data with search and user-management APIs, the MCP Server streamlines common workflows like root-cause investigations, access revocation, and exporting logs for retention policies.

Features

• Collects and stores authentication and activity audit logs from Descope
• Full-text and fielded search across audit events (timestamps, user IDs, IPs, actions)
• User administration endpoints: list, create, update, disable/enable accounts
• Role-based access controls for admin API access (configurable via environment)
• Exportable logs in JSON/CSV formats for compliance and archival
• Docker-friendly and easy to run locally for development and testing

Installation / Configuration

Prerequisites: Node.js (14+), npm or Docker. Clone the repo and configure environment variables.

Clone and run locally:

git clone https://github.com/descope-sample-apps/descope-mcp-server.git
cd descope-mcp-server
npm install
cp .env.example .env
# Edit .env to set your keys and preferences
npm run start

Common environment variables (add these to .env):

PORT=3000
DESCOPE_PROJECT_ID=your-descope-project-id
DESCOPE_KEY_ID=your-key-id
DESCOPE_KEY_SECRET=your-key-secret
ADMIN_API_KEY=some-secure-key
DATABASE_URL=postgres://user:pass@localhost:5432/mcpdb   # optional
LOG_RETENTION_DAYS=90

Run with Docker:

docker build -t descope-mcp-server .
docker run -e DESCOPE_PROJECT_ID=... -e DESCOPE_KEY_SECRET=... -e ADMIN_API_KEY=... -p 3000:3000 descope-mcp-server

If you plan to store logs persistently, provide a DATABASE_URL for PostgreSQL (or follow repository docs for alternatives such as SQLite). Without a DB, some implementations may default to in-memory storage for development.

Available Tools / Resources

• GitHub repository: https://github.com/descope-sample-apps/descope-mcp-server
• Descope documentation: https://docs.descope.com (for authentication and keys)
• Postman or cURL can be used to consume the admin APIs
• Optional: Integrations for external log storage/export (S3, SIEM) — configure via env vars

API Reference (common endpoints)

Endpoint summary:

Example: search audit logs

curl -X POST "http://localhost:3000/api/audit/search" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "failed login",
    "filters": { "userId": "user-123", "from": "2026-01-01T00:00:00Z" },
    "limit": 50,
    "sort": "timestamp:desc"
  }'

Example: disable a user

curl -X POST "http://localhost:3000/api/users/user-123/disable" \
  -H "Authorization: Bearer $ADMIN_API_KEY"

Responses are JSON with consistent paging metadata for list endpoints.

Use Cases

• Incident investigation: An operator can search for “failed login” within a time range, filter by IP address, and export matching events for analysis. This helps quickly identify brute-force attempts or suspicious behavior.
• Compliance reporting: Security teams can schedule exports of authentication events for a retention window and provide auditors with a CSV/JSON snapshot of activity over a compliance period.
• User lifecycle management: Administrators can disable or enable accounts from the same interface used to view audit history — useful when remediating compromised credentials or enforcing access changes.
• Support and troubleshooting: Customer support agents can look up a user’s recent authentication events to diagnose MFA issues, failed enrollments, or to confirm successful resets.
• Centralized security telemetry: Combine Descope authentication events with other telemetry (via a configured external archive) to feed SIEM or monitoring dashboards.

Getting Help and Contributing

• Report issues and feature requests via the GitHub repository issues page.
• Contributions are welcome: fork, implement improvements, and open a pull request.
• For Descope-specific authentication questions, consult Descope docs or contact Descope support.

This server is designed to be extendable: add connectors for external log storage, adapt search indexing to your stack, or integrate role-based admin controls to fit organization policies.