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

• opal-mcp
• Build the image
• Run the container
  • Maturity
  • Contributions

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 Name	Description	Default
API_TOKEN	The API token for MCP server authentication	Required for MCP server
PORT	The port number for the MCP server	32000
SERVER_URL	The base URL for the Opal API	https://api.opal.dev/v1
LOG_LEVEL	Logging level for the MCP server	info

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.

Claude installation steps

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>"
      ]
    }
  }
}

Cursor installation steps

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

Available methods

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

• getBundles - Returns a list of Bundle objects.
• createBundle - Creates a bundle.
• getBundle - Returns a Bundle object.
• deleteBundle - Deletes a bundle.
• updateBundle - Updates a bundle.
• getBundleResources - Returns a list of Resource objects in a given bundle.
• addBundleResource - Adds a resource to a bundle.
• removeBundleResource - Removes a resource from a bundle.
• getBundleGroups - Returns a list of Group objects in a given bundle.
• addBundleGroup - Adds a group to a bundle.
• removeBundleGroup - Removes a group from a bundle.
• getBundleVisibility - Gets the visibility of the bundle.
• setBundleVisibility - Sets the visibility of the bundle.

configurationTemplates

• getConfigurationTemplates - Returns a list of ConfigurationTemplate objects.
• createConfigurationTemplate - Creates a configuration template.
• updateConfigurationTemplate - Update a configuration template.
• deleteConfigurationTemplate - Deletes a configuration template.

events

• events - Returns a list of Event objects.

groupBindings

• getGroupBindings - Returns a list of GroupBinding objects.
• createGroupBinding - Creates a group binding.
• updateGroupBindings - Bulk updates a list of group bindings.
• getGroupBinding - Returns a GroupBinding object.
• deleteGroupBinding - Deletes a group binding.

groups

• getGroups - Returns a list of groups for your organization.
• updateGroups - Bulk updates a list of groups.
• createGroup - Creates an Opal group or imports a remote group.
• getGroup - Returns a Group object.
• deleteGroup - Deletes a group.
• getGroupMessageChannels - Gets the list of audit and reviewer message channels attached to a group.
• setGroupMessageChannels - Sets the list of audit message channels attached to a group.
• getGroupOnCallSchedules - Gets the list of on call schedules attached to a group.
• setGroupOnCallSchedules - Sets the list of on call schedules attached to a group.
• getGroupResources - Gets the list of resources that the group gives access to.
• setGroupResources - Sets the list of resources that the group gives access to.
• getGroupContainingGroups - Gets the list of groups that the group gives access to.
• addGroupContainingGroup - Creates a new containing group.
• getGroupContainingGroup - Gets a specific containing group for a group.
• removeGroupContainingGroup - Removes a containing group from a group.
• addGroupResource - Adds a resource to a group.
• getGroupVisibility - Gets the visibility of this group.
• setGroupVisibility - Sets the visibility of this group.
• getGroupReviewers - Gets the list of owner IDs of the reviewers for a group. ⚠️ Deprecated
• setGroupReviewers - Sets the list of reviewers for a group. ⚠️ Deprecated
• getGroupReviewerStages - Gets the list of reviewer stages for a group. ⚠️ Deprecated
• setGroupReviewerStages - Sets the list of reviewer stages for a group. ⚠️ Deprecated
• getGroupTags - Returns all tags applied to the group.
• getGroupUsers - Gets the list of users for this group.
• updateGroupUser - Updates a user's access level or duration in this group.
• addGroupUser - Adds a user to this group.
• deleteGroupUser - Removes a user's access from this group.

idpGroupMappings

• getIdpGroupMappings - Returns the configured set of available IdpGroupMapping objects for an Okta app.
• updateIdpGroupMappings - Updates the list of available IdpGroupMapping objects for an Okta app.
• deleteIdpGroupMappings - Deletes an IdpGroupMapping object.

messageChannels

• getMessageChannels - Returns a list of MessageChannel objects.
• createMessageChannel - Creates a MessageChannel objects.
• getMessageChannel - Gets a MessageChannel object.

nonHumanIdentities

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

onCallSchedules

• getOnCallSchedules - Returns a list of OnCallSchedule objects.
• createOnCallSchedule - Creates a OnCallSchedule objects.
• getOnCallSchedule - Gets a OnCallSchedule object.

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. ⚠️ Deprecated
• getRequest - Returns a request by ID.
• approveRequest - Approve an access request

resources

• getResources - Returns a list of resources for your organization.
• updateResources - Bulk updates a list of resources.
• createResource - Creates a resource. See here for details about importing resources.
• getResource - Retrieves a resource.
• deleteResource - Deletes a resource.
• getResourceMessageChannels - Gets the list of audit message channels attached to a resource.
• setResourceMessageChannels - Sets the list of audit message channels attached to a resource.
• getResourceVisibility - Gets the visibility of this resource.
• setResourceVisibility - Sets the visibility of this resource.
• getResourceReviewers - Gets the list of owner IDs of the reviewers for a resource.
• setResourceReviewers - Sets the list of reviewers for a resource.
• getResourceReviewerStages - Gets the list reviewer stages for a resource.
• setResourceReviewerStages - Sets the list of reviewer stages for a resource.
• getResourceNhis - Gets the list of non-human identities with access to this resource.
• getResourceUsers - Gets the list of users for this resource.
• addResourceNhi - Gives a non-human identity access to this resource.
• deleteResourceNhi - Removes a non-human identity's direct access from this resource.
• addResourceUser - Adds a user to this resource.
• updateResourceUser - Updates a user's access level or duration on this resource.
• deleteResourceUser - Removes a user's direct access from this resource.
• getResourceUser - Returns information about a specific user's access to a resource.
• resourceUserAccessStatusRetrieve - Get user's access status to a resource. ⚠️ Deprecated
• getResourceTags - Returns all tags applied to the resource.
• getResourceScopedRolePermissions - Returns all the scoped role permissions that apply to the given resource. Only OPAL_SCOPED_ROLE resource type supports this field.
• setResourceScopedRolePermissions - Sets all the scoped role permissions on an OPAL_SCOPED_ROLE resource.

scopedRolePermissions

• getResourceScopedRolePermissions - Returns all the scoped role permissions that apply to the given resource. Only OPAL_SCOPED_ROLE resource type supports this field.
• setResourceScopedRolePermissions - Sets all the scoped role permissions on an OPAL_SCOPED_ROLE resource.

sessions

• sessions - Returns a list of Session objects.

tags

• getTagByID - UNSTABLE. May be removed at any time. Gets a tag with the given id.
• deleteTagByID - UNSTABLE. May be removed at any time. Deletes a tag with the given id.
• getTag - Gets a tag with the given key and value.
• createTag - Creates a tag with the given key and value.
• getTags - Returns a list of tags created by your organization.
• addUserTag - Applies a tag to a user.
• removeUserTag - Removes a tag from a user.
• addGroupTag - Applies a tag to a group.
• removeGroupTag - Removes a tag from a group.
• addResourceTag - Applies a tag to a resource.
• removeResourceTag - Removes a tag from a resource.

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.