OneLogin MCP Server

A Model Context Protocol server providing comprehensive access to the OneLogin API. Enables Claude Desktop, OpenCode, and other MCP clients to manage users, apps, roles, authentication, and security settings.

Overview

This server provides tools covering a comprehensive set of supported OneLogin API endpoints:

• Identity Management: Users, roles, groups
• Applications: Apps, connectors, SAML, OAuth
• Authentication: MFA, sessions, risk rules
• Security: API authorization
• Configuration: Brands, mappings
• Operations: Events, reports, rate limits

All tools include comprehensive descriptions with warnings, best practices, and return data specifications.

Installation

Prerequisites

• OneLogin API credentials (OAuth2 client ID and secret)
• An AI client such as OpenCode, Claude Desktop, Copilot CLI, or Claude Code

Setup

Option 1: Environment Variables (Recommended)

Configure credentials directly in Claude Desktop config - no separate setup required.

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Single environment:

{
  "mcpServers": {
    "onelogin": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_URL": "https://mycompany.onelogin.com",
        "ONELOGIN_CLIENT_ID": "your_client_id",
        "ONELOGIN_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Multiple environments (production/test separation):

{
  "mcpServers": {
    "onelogin-prod": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_URL": "https://company.onelogin.com",
        "ONELOGIN_CLIENT_ID": "prod_client_id",
        "ONELOGIN_CLIENT_SECRET": "prod_secret"
      }
    },
    "onelogin-test": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_URL": "https://company-test.onelogin.com",
        "ONELOGIN_CLIENT_ID": "test_client_id",
        "ONELOGIN_CLIENT_SECRET": "test_secret"
      }
    }
  }
}

Optional environment variables:

• ONELOGIN_USE_PREPROD: Set to "true" for preprod environments
• ONELOGIN_LEGACY_KEY: Legacy API key (rarely needed)
• ONELOGIN_SERVER: Server name for logging (defaults to "default")

Restart Claude Desktop completely after configuration.

OpenCode Configuration

For OpenCode users, add to ~/.config/opencode/mcp.json:

Single environment:

{
  "mcpServers": {
    "onelogin": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_URL": "https://mycompany.onelogin.com",
        "ONELOGIN_CLIENT_ID": "your_client_id",
        "ONELOGIN_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Multiple environments:

{
  "mcpServers": {
    "onelogin-prod": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_URL": "https://company.onelogin.com",
        "ONELOGIN_CLIENT_ID": "prod_client_id",
        "ONELOGIN_CLIENT_SECRET": "prod_secret"
      }
    },
    "onelogin-test": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_URL": "https://company-test.onelogin.com",
        "ONELOGIN_CLIENT_ID": "test_client_id",
        "ONELOGIN_CLIENT_SECRET": "test_secret"
      }
    }
  }
}

Restart OpenCode after configuration.

Option 2: Setup Script (servers.json)

Alternative method using a configuration file:

1. Install the package:

npm install -g @onelogin/onelogin-mcp

2. Configure OneLogin credentials:

npx onelogin-mcp-setup

Enter your OneLogin server details when prompted:

• Server name (e.g., "Production", "Test")
• OneLogin subdomain URL (e.g., https://mycompany.onelogin.com)
• OAuth2 client ID and secret

Configuration is stored in ~/.config/onelogin-mcp/servers.json.

3. Add to Claude Desktop config:

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Single environment:

{
  "mcpServers": {
    "onelogin": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"]
    }
  }
}

Multiple environments (reference servers by name):

{
  "mcpServers": {
    "onelogin-prod": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_SERVER": "Production"
      }
    },
    "onelogin-test": {
      "command": "npx",
      "args": ["-y", "@onelogin/onelogin-mcp"],
      "env": {
        "ONELOGIN_SERVER": "Test"
      }
    }
  }
}

4. Restart Claude Desktop completely.

Usage

Use natural language to interact with OneLogin:

List all users with email ending in @example.com
Get details for user ID 12345
Create a user [email protected] with firstname John, lastname Doe
Assign roles [123, 456] to user 789
Generate MFA token for user 101112
List all SAML apps

Claude will select the appropriate tool, call the OneLogin API, and present results.

API Coverage

This server provides 148 tools organized into 6 major categories:

Identity & Access (59 tools)

• Users (14)
• Roles (13)
• Privileges (11)
• Groups (6)
• Mappings (15)

Applications (18 tools)

• Apps (15)
• Connectors (3)

Authentication (21 tools)

• MFA (10)
• Sessions (5)
• SAML (2)
• OAuth Tokens (2)
• Invite Links (2)

Security (37 tools)

• Risk Rules (6)
• Smart Hooks (10)
• API Authorization (21)

Customization (6 tools)

• Brands (6)

Monitoring (7 tools)

• Events (2)
• Reports (3)
• Rate Limits (2)

Configuration

Credential Management

The server supports two configuration methods:

1. Environment Variables (recommended): Set ONELOGIN_URL, ONELOGIN_CLIENT_ID, and ONELOGIN_CLIENT_SECRET in your MCP client config (see Installation above)
2. Configuration File: Use npx onelogin-mcp-setup to store credentials in ~/.config/onelogin-mcp/servers.json

Environment variables take precedence over the configuration file. See the Installation section above for complete configuration examples.

Optional Environment Variables

• ONELOGIN_USE_PREPROD: Set to "true" for preprod environments
• ONELOGIN_LEGACY_KEY: Legacy API key (rarely needed)
• ONELOGIN_SERVER: Server name for logging (defaults to "default") or to select a named server from servers.json

Response Format

All tools return structured responses:

{
  "success": true,
  "request_id": "68F194DE-0A0D05A2-55F8-0A0F6C42-01BB-62EAE-0008",
  "status": 200,
  "data": {
    // Tool-specific data
  }
}

The request_id matches the x-request-id HTTP header for tracing in Datadog and OneLogin logs.

Troubleshooting

Server not appearing in Claude Desktop

1. Verify JSON config syntax
2. Ensure absolute path to index.js
3. Restart Claude Desktop completely (quit and reopen)

"spawn bun ENOENT" error

Claude cannot find the Bun runtime. Solutions:

# Verify Bun is installed
which bun

# If not found, install Bun
curl -fsSL https://bun.sh/install | bash

# Or use full path in config
{
  "command": "/Users/yourname/.bun/bin/bun",
  "args": ["run", "/path/to/index.js"]
}

Authentication errors

1. If using environment variables: Verify ONELOGIN_URL, ONELOGIN_CLIENT_ID, and ONELOGIN_CLIENT_SECRET in Claude Desktop config
2. If using servers.json: Verify credentials in ~/.config/onelogin-mcp/servers.json
3. Ensure OAuth2 client has API permissions in OneLogin admin panel
4. Check client_id and client_secret are for API v2

Wrong environment

Using environment variables: Each MCP server entry has its own credentials - verify you're talking to the correct server instance in Claude.

Using servers.json: Check the ONELOGIN_SERVER environment variable in Claude Desktop config matches a server name in servers.json.

Project Structure

onelogin-mcp/
├── index.js                    # MCP server entry point
├── setup.js                    # Interactive credential setup
├── lib/
│   ├── config.js               # Credential management
│   ├── onelogin-api.js         # OAuth2 client with token caching
│   └── tools/
│       ├── registry.js         # Tool registry and dispatcher
│       ├── users.js            # User management (10 tools)
│       ├── roles.js            # Role management (13 tools)
│       ├── privileges.js       # Privilege management (11 tools)
│       ├── apps.js             # App management (7 tools)
│       ├── mfa.js              # MFA management (11 tools)
│       ├── mappings.js         # User mappings (14 tools)
│       ├── smart-hooks.js      # Smart Hooks (8 tools)
│       ├── risk-rules.js       # Risk rules (6 tools)
│       ├── api-authorization.js # OAuth scopes (17 tools)
│       ├── sessions.js         # Session tokens (5 tools)
│       ├── brands.js           # Branding (6 tools)
│       ├── connectors.js       # App catalog (3 tools)
│       ├── reports.js          # Analytics (3 tools)
│       ├── rate-limits.js      # API throttling (2 tools)
│       ├── saml.js             # SAML assertions (2 tools)
│       ├── invite-links.js     # Password resets (2 tools)
│       ├── oauth-tokens.js     # OAuth tokens (2 tools)
│       ├── events.js           # Audit logs (2 tools)
│       └── groups.js           # User groups (6 tools)
├── package.json
├── CONTRIBUTING.md
├── PROGRESS.md
└── README.md

Development

See CONTRIBUTING.md for guidelines on adding new tools.

Key conventions:

• Tool descriptions include warnings, best practices, and return data structure
• All modules export tools array and handlers object
• Registry auto-discovers tools from module imports

Releasing

To publish a new version to npm:

1. Merge your changes to the main branch

2. Create a GitHub Release:

   • Go to Releases → "Draft a new release"
   • Create a new tag with the version (e.g., v1.1.0)
   • Set the release title (e.g., "v1.1.0 - MFA API fixes")
   • Add release notes describing the changes
   • Click "Publish release"

3. Automatic Publishing: The GitHub Action will:

   • Extract the version from the release tag (strips v prefix)
   • Update package.json with the new version
   • Publish to npm under @onelogin/onelogin-mcp

Version Format: Use semantic versioning (MAJOR.MINOR.PATCH)

• MAJOR: Breaking API changes
• MINOR: New features, backward compatible
• PATCH: Bug fixes, backward compatible

Manual Publishing (if needed):

• Go to Actions → "Publish Package" → "Run workflow"
• Optionally specify a version override

Support

• GitHub Issues
• OneLogin API Documentation
• Model Context Protocol

License

MIT