Opal API

Uma API RESTful para interagir programaticamente com a plataforma Opal Security.

GitHub
4
Experimente este MCPPatrocinado

Documentação

opal-mcp

SDK TypeScript amigável para desenvolvedores e com segurança de tipos, especificamente criado para aproveitar a API opal-mcp.

Resumo

Opal API: A Opal API é uma API RESTful que permite interagir com a plataforma Opal Security programaticamente.

Índice

Servidor Model Context Protocol (MCP)

Este SDK também é um servidor MCP instalável, onde os vários métodos do SDK são expostos como ferramentas que podem ser invocadas por aplicações de IA.

⚠️ AVISO: Node.js v20 ou superior é necessário para executar o servidor MCP a partir do npm.

Gerando uma Chave de API

Para autenticar com a Opal API, você precisará gerar um token de API:

  1. Faça login no painel da Opal como Administrador
  2. Navegue até a página Configurações
  3. Selecione a seção Tokens de API
  4. Clique em "Gerar novo token"
  5. Escolha o nível de acesso apropriado:
    • Somente leitura: Para aplicações que precisam apenas visualizar recursos
    • Acesso total: Para aplicações que precisam criar ou modificar recursos
  6. Defina uma data de expiração (opcional, mas recomendado por segurança)
  7. Adicione um rótulo descritivo para identificar a finalidade do token
  8. Salve o token com segurança - ele será exibido apenas uma vez

Se um token for comprometido, você pode revogá-lo a qualquer momento na página de Administração da Opal.

Para mais informações, consulte a Documentação de Autenticação da Opal API.

Variáveis de Ambiente

As seguintes variáveis de ambiente podem ser usadas para configurar o SDK e o servidor MCP:

Nome da VariávelDescriçãoPadrão
API_TOKENO token de API para autenticação do servidor MCPObrigatório para o servidor MCP
PORTO número da porta para o servidor MCP32000
SERVER_URLA URL base para a Opal APIhttps://api.opal.dev/v1
LOG_LEVELNível de registro para o servidor MCPinfo

Instalação

A biblioteca pode ser instalada com os gerenciadores de pacotes npm, pnpm, bun ou 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.

[!NOTE] Este pacote é publicado com suporte a CommonJS e ES Modules (ESM).

Etapas de instalação do Claude

Adicione a seguinte definição de servidor ao seu arquivo claude_desktop_config.json:

{
  "mcpServers": {
    "OpalMcp": {
      "command": "npx",
      "args": [
        "-y", "--package", "opal-mcp",
        "--",
        "mcp", "start",
        "--bearer-auth", "<API_TOKEN>"
      ]
    }
  }
}
Etapas de instalação do Cursor

Crie um arquivo .cursor/mcp.json na raiz do seu projeto com o seguinte conteúdo:

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

Você também pode executar servidores MCP como um binário independente, sem dependências adicionais. Você deve baixar esses binários das versões disponíveis no 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

Se o repositório for privado, você deve adicionar seu PAT do Github para baixar uma versão -H "Authorization: Bearer {GITHUB_PAT}".

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

Para uma lista completa de argumentos do servidor, execute:

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

Executando o Servidor MCP com Docker

O SDK inclui um Dockerfile e docker-compose.yaml para facilitar a conteinerização e implantação.

Usando docker-compose

  1. Crie um arquivo .env com sua configuração:

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

  2. Execute o servidor usando docker-compose:

    docker-compose up -d

  3. Configure seu cliente MCP para conectar ao servidor adicionando o seguinte ao seu arquivo de configuração:

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

Criando e executando manualmente

Você também pode criar e executar a imagem Docker diretamente:

# 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

Solução de Problemas do MCP

Aqui estão alguns problemas comuns que você pode encontrar ao usar o servidor MCP e como resolvê-los:

Problemas de Conexão

  • Servidor Não Iniciando

    • Verifique se a versão do Node.js é v20 ou superior
    • Verifique se a porta 32000 já está em uso
    • Certifique-se de ter permissões adequadas para executar o servidor
    • Tente executar com LOG_LEVEL=debug para uma saída mais detalhada

  • Falhas de Autenticação

    • Verifique se seu token de API é válido e não expirou
    • Verifique se o token tem as permissões corretas
    • Certifique-se de que o token esteja configurado corretamente nas variáveis de ambiente
    • Confirme se o SERVER_URL aponta para o ambiente correto

Problemas de Desempenho

  • Tempos de Resposta Lentos
    • Verifique a conectividade de rede com a Opal API
    • Esteja ciente do limite de tokens para o modelo que você está usando e o número de resultados paginados
    • Improvável. Verifique se você não está atingindo os limites de taxa Limites de Taxa da Opal API

Problemas de Integração

  • Cursor/Claude Não Conectando
    • Verifique se sua configuração mcp.json está correta
    • Certifique-se de que o servidor MCP esteja em execução antes de iniciar o Cursor/Claude
    • Verifique se o token de autenticação bearer está formatado corretamente
    • Confirme se o endpoint SSE está acessível
    • Certifique-se de que apenas uma janela do Cursor/Claude esteja aberta

Mensagens de Erro Comuns

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

    • Outro processo está usando a porta 32000
    • Pare o outro processo ou altere a variável de ambiente PORT

  • Error: Invalid bearer auth token

    • O token de API fornecido é inválido ou malformado
    • Gere um novo token no painel da Opal

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

    • Atualize sua instalação do Node.js para a versão 20 ou superior

Para ajuda adicional, você pode:

  • Definir LOG_LEVEL=debug para logs mais detalhados
  • Consultar a Documentação da Opal API
  • Abrir um problema no repositório do GitHub

Recursos e Operações Disponíveis

Métodos disponíveis

accessRules

  • createAccessRule - Cria uma nova configuração de regra de acesso para o group_id fornecido.
  • getAccessRule - Retorna uma lista de configurações de regra de acesso dado o group_id da regra de acesso.
  • updateAccessRule - Atualiza a configuração da regra de acesso para o group_id fornecido.

apps

  • getApps - Retorna uma lista de objetos App.
  • getApp - Retorna um objeto App.
  • getSyncErrors - Retorna uma lista de erros de sincronização recentes que ocorreram desde a última sincronização bem-sucedida.

bundles

configurationTemplates

events

  • events - Retorna uma lista de objetos Event.

groupBindings

groups

idpGroupMappings

messageChannels

nonHumanIdentities

  • getNhis - Retorna uma lista de identidades não humanas para sua organização.

onCallSchedules

owners

  • getOwners - Retorna uma lista de objetos Owner.
  • createOwner - Cria um proprietário.
  • updateOwners - Atualiza em massa uma lista de proprietários.
  • getOwner - Retorna um objeto Owner.
  • deleteOwner - Exclui um proprietário.
  • getOwnerFromName - Retorna um objeto Owner. Não suporta proprietários com / no nome; use /owners?name=... em vez disso.
  • getOwnerUsers - Obtém a lista de usuários para este proprietário, em ordem de prioridade de escalonamento, se aplicável.
  • setOwnerUsers - Define a lista de usuários para este proprietário. Se o escalonamento estiver habilitado, a ordem desta lista é a ordem de prioridade de escalonamento dos usuários. Se o proprietário tiver um grupo de origem, não será possível adicionar ou remover usuários desta lista.

requests

  • getRequests - Retorna uma lista de solicitações da sua organização que é visível pelo administrador.
  • createRequest - Cria uma solicitação de acesso.
  • getRequestsRelay - Retorna uma lista paginada de solicitações usando paginação por cursor no estilo Relay. :warning: Obsoleto
  • getRequest - Retorna uma solicitação por ID.
  • approveRequest - Aprova uma solicitação de acesso.

resources

scopedRolePermissions

sessions

  • sessions - Retorna uma lista de objetos Session.

tags

  • getTagByID - INSTÁVEL. Pode ser removido a qualquer momento. Obtém uma tag com o ID fornecido.
  • deleteTagByID - INSTÁVEL. Pode ser removido a qualquer momento. Exclui uma tag com o ID fornecido.
  • getTag - Obtém uma tag com a chave e o valor fornecidos.
  • createTag - Cria uma tag com a chave e o valor fornecidos.
  • getTags - Retorna uma lista de tags criadas pela sua organização.
  • addUserTag - Aplica uma tag a um usuário.
  • removeUserTag - Remove uma tag de um usuário.
  • addGroupTag - Aplica uma tag a um grupo.
  • removeGroupTag - Remove uma tag de um grupo.
  • addResourceTag - Aplica uma tag a um recurso.
  • removeResourceTag - Remove uma tag de um recurso.

uars

  • getUARs - Retorna uma lista de objetos UAR.
  • createUar - Inicia uma Revisão de Acesso de Usuário.
  • getUar - Recupera um UAR específico.

users

  • user - Recupera informações detalhadas do usuário do Opal. Este endpoint foi projetado para buscar detalhes do usuário por ID do usuário (UUID) ou endereço de e-mail. O endpoint segue uma regra de precedência estrita em que user_id tem prioridade sobre o e-mail se ambos forem fornecidos.

Notas importantes de implementação:

  • Exatamente um identificador (user_id OU e-mail) deve ser fornecido
  • Retorna um objeto User completo com todos os metadados associados
  • Adequado para verificação de usuário e recuperação de dados de perfil
  • Recomendado para fluxos de trabalho de sincronização de usuários do MCP

Autenticação:

  • Requer autenticação válida da API
  • Respeita as regras de autorização padrão do Opal
  • getUsers - Retorna uma lista de usuários da sua organização.
  • getUserTags - Retorna todas as tags aplicadas ao usuário.

Paginação

Alguns dos endpoints deste SDK suportam paginação. Para usar a paginação, você faz suas chamadas de SDK normalmente, mas o objeto de resposta retornado também será um iterável assíncrono que pode ser consumido usando a sintaxe for await...of.

Aqui está um exemplo de uma dessas chamadas de paginação:

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

Maturidade

Este SDK está em beta e pode haver mudanças que quebram a compatibilidade entre versões sem uma atualização de versão principal. Portanto, recomendamos fixar o uso a uma versão específica do pacote. Dessa forma, você pode instalar a mesma versão todas as vezes sem mudanças que quebrem a compatibilidade, a menos que esteja intencionalmente procurando a versão mais recente.

Contribuições

Embora valorizemos contribuições de código aberto para este SDK, esta biblioteca é gerada programaticamente. Quaisquer alterações manuais adicionadas aos arquivos internos serão sobrescritas na próxima geração. Estamos ansiosos para ouvir seus comentários. Sinta-se à vontade para abrir um PR ou uma issue com uma prova de conceito e faremos o possível para incluí-la em uma versão futura.

SDK criado por Speakeasy

Consulte CONTRIBUTING.md para obter diretrizes sobre como contribuir com este projeto.