Opal API

Una API RESTful para interactuar programáticamente con la plataforma Opal Security.

GitHub
4
Prueba este MCPPatrocinado

Documentación

opal-mcp

SDK de TypeScript, amigable para desarrolladores y con seguridad de tipos, diseñado específicamente para aprovechar la API de opal-mcp.

Resumen

API de Opal: La API de Opal es una API RESTful que te permite interactuar con la plataforma de seguridad de Opal de forma programática.

Tabla de contenidos

Servidor del Protocolo de Contexto de Modelo (MCP)

Este SDK también es un servidor MCP instalable donde los diversos métodos del SDK se exponen como herramientas que pueden ser invocadas por aplicaciones de IA.

⚠️ ADVERTENCIA: Se requiere Node.js v20 o superior para ejecutar el servidor MCP desde npm.

Generación de una clave de API

Para autenticarte con la API de Opal, necesitarás generar un token de API:

  1. Inicia sesión en el panel de Opal como Administrador
  2. Navega a la página de Configuración
  3. Selecciona la sección de Tokens de API
  4. Haz clic en "Generar nuevo token"
  5. Elige el nivel de acceso adecuado:
    • Solo lectura: Para aplicaciones que solo necesitan ver recursos
    • Acceso completo: Para aplicaciones que necesitan crear o modificar recursos
  6. Establece una fecha de expiración (opcional pero recomendada por seguridad)
  7. Agrega una etiqueta descriptiva para identificar el propósito del token
  8. Guarda el token de forma segura: solo se mostrará una vez

Si un token se ve comprometido, puedes revocarlo en cualquier momento desde la página de Administración de Opal.

Para más información, consulta la Documentación de autenticación de la API de Opal.

Variables de entorno

Las siguientes variables de entorno se pueden usar para configurar el SDK y el servidor MCP:

Nombre de la variableDescripciónValor predeterminado
API_TOKENEl token de API para la autenticación del servidor MCPRequerido para el servidor MCP
PORTEl número de puerto para el servidor MCP32000
SERVER_URLLa URL base para la API de Opalhttps://api.opal.dev/v1
LOG_LEVELNivel de registro para el servidor MCPinfo

Instalación

La biblioteca se puede instalar con cualquiera de los gestores de paquetes npm, pnpm, bun o yarn.

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.

[!NOTA] Este paquete se publica con soporte para CommonJS y Módulos ES (ESM).

Pasos de instalación para Claude

Agrega la siguiente definición de servidor a tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "OpalMcp": {
      "command": "npx",
      "args": [
        "-y", "--package", "opal-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}
Pasos de instalación para Cursor

Crea un archivo .cursor/mcp.json en la raíz de tu proyecto con el siguiente contenido:

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

También puedes ejecutar servidores MCP como un binario independiente sin dependencias adicionales. Debes extraer estos binarios de las versiones disponibles de Github:

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

Si el repositorio es privado, debes agregar tu PAT de Github para descargar una versión -H "Authorization: Bearer {GITHUB_PAT}".

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

Para obtener una lista completa de los argumentos del servidor, ejecuta:

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

Ejecutar el servidor MCP con Docker

El SDK incluye un Dockerfile y docker-compose.yaml para facilitar la contenedorización y el despliegue.

Usando docker-compose

  1. Crea un archivo .env con tu configuración:

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

  2. Ejecuta el servidor usando docker-compose:

    docker-compose up -d

  3. Configura tu cliente MCP para conectarse al servidor agregando lo siguiente a tu archivo de configuración:

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

Construir y ejecutar manualmente

También puedes construir y ejecutar la imagen de Docker directamente:

# 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

Solución de problemas de MCP

Aquí hay algunos problemas comunes que podrías encontrar al usar el servidor MCP y cómo resolverlos:

Problemas de conexión

  • El servidor no se inicia

    • Verifica que la versión de Node.js sea v20 o superior
    • Comprueba si el puerto 32000 ya está en uso
    • Asegúrate de tener los permisos adecuados para ejecutar el servidor
    • Intenta ejecutar con LOG_LEVEL=debug para obtener una salida más detallada

  • Fallos de autenticación

    • Verifica que tu token de API sea válido y no haya expirado
    • Comprueba si el token tiene los permisos correctos
    • Asegúrate de que el token esté configurado correctamente en las variables de entorno
    • Confirma que SERVER_URL apunte al entorno correcto

Problemas de rendimiento

  • Tiempos de respuesta lentos
    • Comprueba la conectividad de red con la API de Opal
    • Ten en cuenta el límite de tokens para el modelo que estás usando y la cantidad de resultados paginados
    • Poco probable. Verifica que no estés alcanzando los límites de tasa Límites de tasa de la API de Opal

Problemas de integración

  • Cursor/Claude no se conectan
    • Verifica que tu configuración de mcp.json sea correcta
    • Asegúrate de que el servidor MCP esté ejecutándose antes de iniciar Cursor/Claude
    • Comprueba si el token de autenticación de portador está formateado correctamente
    • Confirma que la URL del endpoint SSE sea accesible
    • Asegúrate de que solo haya una ventana de Cursor/Claude abierta

Mensajes de error comunes

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

    • Otro proceso está usando el puerto 32000
    • Detén el otro proceso o cambia la variable de entorno PORT

  • Error: Invalid bearer auth token

    • El token de API proporcionado no es válido o está mal formado
    • Genera un nuevo token desde el panel de Opal

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

    • Actualiza tu instalación de Node.js a la versión 20 o superior

Para obtener ayuda adicional, puedes:

  • Configurar LOG_LEVEL=debug para obtener registros más detallados
  • Consultar la Documentación de la API de Opal
  • Reportar un problema en el repositorio de GitHub

Recursos y operaciones disponibles

Métodos disponibles

accessRules

  • createAccessRule - Crea una nueva configuración de regla de acceso para el group_id dado.
  • getAccessRule - Devuelve una lista de configuraciones de reglas de acceso dado el group_id de la regla de acceso.
  • updateAccessRule - Actualiza la configuración de la regla de acceso para el group_id dado.

apps

  • getApps - Devuelve una lista de objetos App.
  • getApp - Devuelve un objeto App.
  • getSyncErrors - Devuelve una lista de errores de sincronización recientes que han ocurrido desde la última sincronización exitosa.

bundles

configurationTemplates

events

  • events - Devuelve una lista de objetos Event.

groupBindings

groups

idpGroupMappings

messageChannels

nonHumanIdentities

  • getNhis - Devuelve una lista de identidades no humanas para tu organización.

onCallSchedules

owners

  • getOwners - Devuelve una lista de objetos Owner.
  • createOwner - Crea un propietario.
  • updateOwners - Actualiza en masa una lista de propietarios.
  • getOwner - Devuelve un objeto Owner.
  • deleteOwner - Elimina un propietario.
  • getOwnerFromName - Devuelve un objeto Owner. No admite propietarios con / en su nombre; use /owners?name=... en su lugar.
  • getOwnerUsers - Obtiene la lista de usuarios para este propietario, en orden de prioridad de escalamiento si corresponde.
  • setOwnerUsers - Establece la lista de usuarios para este propietario. Si el escalamiento está habilitado, el orden de esta lista es el orden de prioridad de escalamiento de los usuarios. Si el propietario tiene un grupo de origen, no será posible agregar o eliminar usuarios de esta lista.

requests

  • getRequests - Devuelve una lista de solicitudes para su organización que es visible por el administrador.
  • createRequest - Crea una solicitud de acceso.
  • getRequestsRelay - Devuelve una lista paginada de solicitudes utilizando paginación por cursor estilo Relay. :warning: Obsoleto
  • getRequest - Devuelve una solicitud por ID.
  • approveRequest - Aprueba una solicitud de acceso.

resources

scopedRolePermissions

sessions

  • sessions - Devuelve una lista de objetos Session.

tags

  • getTagByID - INESTABLE. Puede eliminarse en cualquier momento. Obtiene una etiqueta con el id dado.
  • deleteTagByID - INESTABLE. Puede eliminarse en cualquier momento. Elimina una etiqueta con el id dado.
  • getTag - Obtiene una etiqueta con la clave y el valor dados.
  • createTag - Crea una etiqueta con la clave y el valor dados.
  • getTags - Devuelve una lista de etiquetas creadas por su organización.
  • addUserTag - Aplica una etiqueta a un usuario.
  • removeUserTag - Elimina una etiqueta de un usuario.
  • addGroupTag - Aplica una etiqueta a un grupo.
  • removeGroupTag - Elimina una etiqueta de un grupo.
  • addResourceTag - Aplica una etiqueta a un recurso.
  • removeResourceTag - Elimina una etiqueta de un recurso.

uars

  • getUARs - Devuelve una lista de objetos UAR.
  • createUar - Inicia una revisión de acceso de usuario.
  • getUar - Recupera un UAR específico.

users

  • user - Recupera información detallada del usuario de Opal. Este endpoint está diseñado para obtener detalles del usuario mediante el ID de usuario (UUID) o la dirección de correo electrónico. El endpoint sigue una regla de precedencia estricta donde user_id tiene prioridad sobre email si ambos se proporcionan.

Notas clave de implementación:

  • Se debe proporcionar exactamente un identificador (user_id O email)
  • Devuelve un objeto User completo con todos los metadatos asociados
  • Adecuado para la verificación de usuarios y la recuperación de datos de perfil
  • Recomendado para flujos de trabajo de sincronización de usuarios de MCP

Autenticación:

  • Requiere autenticación API válida
  • Respeta las reglas de autorización estándar de Opal
  • getUsers - Devuelve una lista de usuarios para su organización.
  • getUserTags - Devuelve todas las etiquetas aplicadas al usuario.

Paginación

Algunos de los endpoints de este SDK admiten paginación. Para usar la paginación, realice sus llamadas al SDK como de costumbre, pero el objeto de respuesta devuelto también será un iterable asíncrono que se puede consumir usando la sintaxis for await...of.

Aquí hay un ejemplo de una llamada de paginación de este tipo:

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();

Madurez

Este SDK está en beta, y puede haber cambios importantes entre versiones sin una actualización de versión principal. Por lo tanto, recomendamos fijar el uso a una versión específica del paquete. De esta manera, puede instalar la misma versión cada vez sin cambios importantes a menos que esté buscando intencionalmente la última versión.

Contribuciones

Si bien valoramos las contribuciones de código abierto a este SDK, esta biblioteca se genera programáticamente. Cualquier cambio manual agregado a los archivos internos se sobrescribirá en la próxima generación. Esperamos recibir sus comentarios. No dude en abrir un PR o un problema con una prueba de concepto y haremos todo lo posible para incluirlo en una versión futura.

SDK Creado por Speakeasy

Consulte CONTRIBUTING.md para obtener pautas sobre cómo contribuir a este proyecto.