Opal API

A RESTful API to programmatically interact with the Opal Security platform.

GitHub

opal-mcp

Developer-friendly & type-safe Typescript SDK specifically catered to leverage opal-mcp API.

Summary

Opal API: The Opal API is a RESTful API that allows you to interact with the Opal Security platform programmatically.

Table of Contents

Model Context Protocol (MCP) Server

This SDK is also an installable MCP server where the various SDK methods are exposed as tools that can be invoked by AI applications.

⚠️ WARNING: Node.js v20 or greater is required to run the MCP server from npm.

Generating an API Key

To authenticate with the Opal API, you'll need to generate an API token:

  1. Log in to the Opal dashboard as an Admin
  2. Navigate to the Settings page
  3. Select the API Tokens section
  4. Click "Generate new token"
  5. Choose the appropriate access level:
    • Read-only: For applications that only need to view resources
    • Full-access: For applications that need to create or modify resources
  6. Set an expiration date (optional but recommended for security)
  7. Add a descriptive label to identify the token's purpose
  8. Save the token securely - it will only be displayed once

If a token is compromised, you can revoke it at any time from the Opal Admin page.

For more information, see the Opal API Authentication Documentation.

Environment Variables

The following environment variables can be used to configure the SDK and MCP server:

Variable NameDescriptionDefault
API_TOKENThe API token for MCP server authenticationRequired for MCP server
PORTThe port number for the MCP server32000
SERVER_URLThe base URL for the Opal APIhttps://api.opal.dev/v1
LOG_LEVELLogging level for the MCP serverinfo

Installation

The library can be installed with either npm, pnpm, bun or yarn package managers.

NPM

npm add opal-mcp

PNPM

pnpm add opal-mcp

Bun

bun add opal-mcp

Yarn

yarn add opal-mcp zod

# Note that Yarn does not install peer dependencies automatically. You will need
# to install zod as shown above.

[!NOTE] This package is published with CommonJS and ES Modules (ESM) support.

Add the following server definition to your claude_desktop_config.json file:

{
  "mcpServers": {
    "OpalMcp": {
      "command": "npx",
      "args": [
        "-y", "--package", "opal-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}

Create a .cursor/mcp.json file in your project root with the following content:

{
  "mcpServers": {
    "OpalMcp": {
      "command": "npx",
      "args": [
        "-y", "--package", "opal-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}

You can also run MCP servers as a standalone binary with no additional dependencies. You must pull these binaries from available Github releases:

curl -L -o mcp-server \
    https://github.com/opalsecurity/opal-mcp/releases/download/v0.0.6/mcp-server-bun-darwin-arm64 && \
chmod +x mcp-server

If the repo is a private repo you must add your Github PAT to download a release -H "Authorization: Bearer {GITHUB_PAT}".

{
  "mcpServers": {
    "Todos": {
      "command": "./DOWNLOAD/PATH/mcp-server",
      "args": [
        "start"
      ]
    }
  }
}

For a full list of server arguments, run:

npx -y --package opal-mcp -- mcp start --help

Running the MCP Server with Docker

The SDK includes a Dockerfile and docker-compose.yaml for easy containerization and deployment.

Using docker-compose

  1. Create a .env file with your configuration:

    BEARER_AUTH=your_api_key_here
PORT=32000
SERVER_URL=https://api.opal.dev/v1
LOG_LEVEL=info

  2. Run the server using docker-compose:

    docker-compose up -d

  3. Configure your MCP client to connect to the server by adding the following to your configuration file:

    {
  "mcpServers": {
    "opal-mcp": {
      "url": "http://localhost:32000/sse",
      "env": {
        "API_KEY": "your_api_key_here"
      }
    }
  }
}

Building and running manually

You can also build and run the Docker image directly:

# Build the image
docker build -t opal-mcp-server .

# Run the container
docker run -p 32000:32000 -e BEARER_AUTH=your_api_key_here opal-mcp-server

Troubleshooting MCP

Here are some common issues you might encounter when using the MCP server and how to resolve them:

Connection Issues

  • Server Not Starting

    • Verify Node.js version is v20 or greater
    • Check if port 32000 is already in use
    • Ensure you have proper permissions to run the server
    • Try running with LOG_LEVEL=debug for more detailed output

  • Authentication Failures

    • Verify your API token is valid and not expired
    • Check if the token has the correct permissions
    • Ensure the token is properly set in the environment variables
    • Confirm the SERVER_URL points to the correct environment

Performance Issues

  • Slow Response Times
    • Check network connectivity to the Opal API
    • Be aware of the token limit for the model you are using and the number of paginated results
    • Unlikely. Verify you're not hitting rate limits Opal API Rate Limits

Integration Issues

  • Cursor/Claude Not Connecting
    • Verify your mcp.json configuration is correct
    • Ensure the MCP server is running before starting Cursor/Claude
    • Check if the bearer auth token is properly formatted
    • Confirm the SSE endpoint URL is accessible
    • Ensure only one Cursor/Claude window is open

Common Error Messages

  • Error: listen EADDRINUSE: address already in use :::32000

    • Another process is using port 32000
    • Either stop the other process or change the PORT environment variable

  • Error: Invalid bearer auth token

    • The provided API token is invalid or malformed
    • Generate a new token from the Opal dashboard

  • Error: Node.js version must be >= 20.0.0

    • Update your Node.js installation to version 20 or greater

For additional help, you can:

  • Set LOG_LEVEL=debug for more detailed logs
  • Check the Opal API Documentation
  • File an issue on the GitHub repository

Available Resources and Operations

accessRules

  • createAccessRule - Creates a new access rule config for the given group_id.
  • getAccessRule - Returns a list of access rule config given the group_id of the access rule.
  • updateAccessRule - Updates the access rule config for the given group_id.

apps

  • getApps - Returns a list of App objects.
  • getApp - Returns an App object.
  • getSyncErrors - Returns a list of recent sync errors that have occurred since the last successful sync.

bundles

configurationTemplates

events

  • events - Returns a list of Event objects.

groupBindings

groups

idpGroupMappings

messageChannels

nonHumanIdentities

  • getNhis - Returns a list of non-human identities for your organization.

onCallSchedules

owners

  • getOwners - Returns a list of Owner objects.
  • createOwner - Creates an owner.
  • updateOwners - Bulk updates a list of owners.
  • getOwner - Returns an Owner object.
  • deleteOwner - Deletes an owner.
  • getOwnerFromName - Returns an Owner object. Does not support owners with / in their name, use /owners?name=... instead.
  • getOwnerUsers - Gets the list of users for this owner, in escalation priority order if applicable.
  • setOwnerUsers - Sets the list of users for this owner. If escalation is enabled, the order of this list is the escalation priority order of the users. If the owner has a source group, adding or removing users from this list won't be possible.

requests

  • getRequests - Returns a list of requests for your organization that is visible by the admin.
  • createRequest - Create an access request
  • getRequestsRelay - Returns a paginated list of requests using Relay-style cursor pagination. :warning: Deprecated
  • getRequest - Returns a request by ID.
  • approveRequest - Approve an access request

resources

scopedRolePermissions

sessions

  • sessions - Returns a list of Session objects.

tags

uars

  • getUARs - Returns a list of UAR objects.
  • createUar - Starts a User Access Review.
  • getUar - Retrieves a specific UAR.

users

  • user - Retrieves detailed user information from Opal. This endpoint is designed to fetch user details by either user ID (UUID) or email address. The endpoint follows a strict precedence rule where user_id takes priority over email if both are provided.

Key Implementation Notes:

  • Exactly one identifier (user_id OR email) must be provided
  • Returns a complete User object with all associated metadata
  • Suitable for user verification and profile data retrieval
  • Recommended for MCP user synchronization workflows

Authentication:

  • Requires valid API authentication
  • Respects standard Opal authorization rules
  • getUsers - Returns a list of users for your organization.
  • getUserTags - Returns all tags applied to the user.

Pagination

Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned response object will also be an async iterable that can be consumed using the for await...of syntax.

Here's an example of one such pagination call:

import { OpalMcp } from "opal-mcp";

const opalMcp = new OpalMcp({
  bearerAuth: process.env["OPALMCP_BEARER_AUTH"] ?? "",
});

async function run() {
  const result = await opalMcp.bundles.getBundles({
    pageSize: 200,
    cursor: "cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw",
    contains: "Engineering",
  });

  for await (const page of result) {
    console.log(page);
  }
}

run();

Maturity

This SDK is in beta, and there may be breaking changes between versions without a major version update. Therefore, we recommend pinning usage to a specific package version. This way, you can install the same version each time without breaking changes unless you are intentionally looking for the latest version.

Contributions

While we value open-source contributions to this SDK, this library is generated programmatically. Any manual changes added to internal files will be overwritten on the next generation. We look forward to hearing your feedback. Feel free to open a PR or an issue with a proof of concept and we'll do our best to include it in a future release.

SDK Created by Speakeasy

See CONTRIBUTING.md for guidelines on contributing to this project.

Related Servers