RAD Security

Servidor MCP do RAD Security

Um servidor Model Context Protocol (MCP) para o RAD Security, que fornece insights de segurança com tecnologia de IA para ambientes Kubernetes e de nuvem.

Conectar (hospedado — recomendado)

O RAD Security executa o servidor MCP para você, então a maioria dos usuários não precisa instalar nem hospedar nada. Aponte seu cliente MCP para o endpoint hospedado e autentique-se com suas credenciais do RAD Security.

• Endpoint: https://api.rad.security/mcp/ — observe a barra final.

• Transporte: HTTP com streaming.

• Autenticação: envie sua credencial no cabeçalho Authorization:

  Authorization: Bearer <access_key_id>:<secret_key>:<account_id>
  

  <access_key_id> e <secret_key> são uma chave de acesso à API do RAD Security (crie uma no console do RAD Security); <account_id> é o ID da sua conta. O servidor autentica cada solicitação com a API do RAD Security — nenhuma credencial é armazenada no servidor.

Uma forma de curta duração Bearer ory_st_<session_token>:<account_id> também funciona, mas os tokens de sessão expiram — prefira uma chave de acesso para qualquer uso de longa duração (por exemplo, Slack / Claude Tag).

Uma conexão para todo um tenant

Para trabalhar em todas as suas contas usando uma única configuração MCP, crie uma chave de acesso no seu tenant e use tenant=<tenant_id> no lugar do ID da conta:

Authorization: Bearer <access_key_id>:<secret_key>:tenant=<tenant_id>

Em uma sessão com escopo de tenant:

• Uma ferramenta list_accounts retorna as contas do tenant.
• As ferramentas com escopo de conta exigem um argumento account_id, que deve ser uma conta filha do tenant. Cada chamada abrange uma conta; os resultados não são combinados entre contas.
• Por padrão, somente ferramentas somente leitura estão disponíveis, pois uma credencial de tenant dá acesso a todas as contas. Para habilitar ferramentas de gravação, envie X-Rad-Readonly: false.

Para o servidor npx/stdio, defina RAD_SECURITY_TENANT_ID sem RAD_SECURITY_ACCOUNT_ID e use RAD_SECURITY_READONLY=false para habilitar ferramentas de gravação.

Claude Code

claude mcp add --transport http rad-security https://api.rad.security/mcp/ \
  --header "Authorization: Bearer <access_key_id>:<secret_key>:<account_id>"

OpenAI Codex CLI

~/.codex/config.toml:

[mcp_servers.rad-security]
url = "https://api.rad.security/mcp/"
http_headers = { "Authorization" = "Bearer <access_key_id>:<secret_key>:<account_id>" }

Ou pela CLI, mantendo o segredo em uma variável de ambiente (export RAD_MCP_TOKEN=<access_key_id>:<secret_key>:<account_id>):

codex mcp add rad-security --url https://api.rad.security/mcp/ --bearer-token-env-var RAD_MCP_TOKEN

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "rad-security": {
      "type": "http",
      "url": "https://api.rad.security/mcp/",
      "headers": {
        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
      }
    }
  }
}

VS Code (GitHub Copilot)

.vscode/mcp.json — observe que a chave wrapper é servers, não mcpServers:

{
  "servers": {
    "rad-security": {
      "type": "http",
      "url": "https://api.rad.security/mcp/",
      "headers": {
        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
      }
    }
  }
}

Gemini CLI

~/.gemini/settings.json — observe que o campo de URL é httpUrl (não url):

{
  "mcpServers": {
    "rad-security": {
      "httpUrl": "https://api.rad.security/mcp/",
      "headers": {
        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
      }
    }
  }
}

Cline

cline_mcp_settings.json — observe que type deve ser exatamente streamableHttp (camelCase):

{
  "mcpServers": {
    "rad-security": {
      "type": "streamableHttp",
      "url": "https://api.rad.security/mcp/",
      "headers": {
        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json — observe que o campo de URL é serverUrl:

{
  "mcpServers": {
    "rad-security": {
      "serverUrl": "https://api.rad.security/mcp/",
      "headers": {
        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>"
      }
    }
  }
}

Outros clientes

A maioria dos clientes MCP aceita um servidor HTTP remoto com streaming, uma URL e um cabeçalho Authorization — somente os nomes dos campos variam. Mantenha a barra final na URL em todos os casos.

Cliente	Local da configuração	Campo de URL	Indicador de transporte	Campo do cabeçalho
Claude Code	claude mcp add	argumento posicional	--transport http	--header
OpenAI Codex CLI	~/.codex/config.toml	url	inferido	http_headers / bearer_token_env_var
Cursor	.cursor/mcp.json	url	type: "http"	headers
VS Code	.vscode/mcp.json (servers)	url	type: "http"	headers
Gemini CLI	~/.gemini/settings.json	httpUrl	inferido	headers
Cline	cline_mcp_settings.json	url	type: "streamableHttp"	headers
Windsurf	~/.codeium/windsurf/mcp_config.json	serverUrl	inferido	headers

Claude.ai / Claude Desktop / Claude Tag (Slack)

Essas interfaces adicionam servidores MCP remotos como conectores, que usam suas próprias configurações de credenciais em vez de um cabeçalho de solicitação bruto. Adicione https://api.rad.security/mcp/ como um conector personalizado e, em seguida, forneça a credencial bearer nas configurações do conector:

• Claude Tag (Slack): adicione o servidor como um plugin cujo .mcp.json aponta para o endpoint e adicione a credencial bearer na guia Credentials do pacote de acesso. Consulte Claude Tag — conectar um servidor MCP personalizado.
• Claude.ai / Desktop: adicione-o em Settings → Connectors; consulte conectores personalizados.

Testar (MCP Inspector ou curl)

npx @modelcontextprotocol/inspector
# Transport:      Streamable HTTP
# URL:            https://api.rad.security/mcp/   (trailing slash)
# Custom headers: { "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>" }

curl -H "authorization: Bearer <access_key_id>:<secret_key>:<account_id>" \
  -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -X POST https://api.rad.security/mcp/ \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

Definir o escopo das ferramentas visíveis para um agente

Por padrão, uma conexão recebe todos os toolkits. Para fornecer a um agente um conjunto menor — reduzindo o uso de contexto/tokens e aplicando o princípio do menor privilégio — adicione um cabeçalho de escopo à conexão junto com Authorization. O subconjunto é aplicado: uma ferramenta fora do escopo fica oculta de tools/list e é rejeitada se for chamada.

Cabeçalho	Efeito
X-Rad-Toolkits: findings, images	somente estes toolkits
X-Rad-Exclude-Toolkits: workflows	todos os toolkits, exceto estes
X-Rad-Readonly: true	somente ferramentas somente leitura (remove as ferramentas de gravação)

Toolkits: containers, clusters, audit, images, kubeobject, runtime, findings, inbox, workflows, knowledge_base, radql, dashboards, integrations. Todos são habilitados por padrão — restrinja-os com os cabeçalhos acima e use X-Rad-Readonly quando quiser excluir todas as ferramentas de gravação.

Exemplo — um agente somente leitura para findings/imagens (qualquer cliente que aceite cabeçalhos; exemplo com Cursor):

{
  "mcpServers": {
    "rad-security-findings": {
      "type": "http",
      "url": "https://api.rad.security/mcp/",
      "headers": {
        "Authorization": "Bearer <access_key_id>:<secret_key>:<account_id>",
        "X-Rad-Toolkits": "findings, images",
        "X-Rad-Readonly": "true"
      }
    }
  }
}

No Claude Code, passe um --header adicional:

claude mcp add --transport http rad-security https://api.rad.security/mcp/ \
  --header "Authorization: Bearer <access_key_id>:<secret_key>:<account_id>" \
  --header "X-Rad-Toolkits: findings, images"

Recursos

Todas as ferramentas exigem autenticação e uma conta no RAD Security. Por padrão, o endpoint hospedado expõe todos os toolkits abaixo; restrinja o escopo de um cliente com X-Rad-Toolkits / X-Rad-Exclude-Toolkits ou remova todas as ferramentas de gravação com X-Rad-Readonly: true.

• Inventário de contas

  • Listar clusters e seus detalhes

• Inventário de contêineres

  • Listar contêineres e seus detalhes

• Findings de segurança

  • Listar e analisar findings de segurança
  • Atualizar o status de um finding de segurança

• Segurança em tempo de execução

  • Obter árvores de processos de contêineres em execução
  • Obter baselines de tempo de execução de contêineres em execução
  • Analisar o comportamento de processos de contêineres em execução

• Auditoria

  • Listar quem acessou um pod via shell

• Imagens e vulnerabilidades

  • Obter SBOMs
  • Listar imagens e suas vulnerabilidades
  • Obter as imagens mais vulneráveis
  • Ignorar / deixar de ignorar CVEs e listar as disposições ativas de CVEs

• Objetos do Kubernetes

  • Obter detalhes de um recurso específico do Kubernetes
  • Listar recursos do Kubernetes

• Caixa de entrada

  • Listar itens da caixa de entrada e seus detalhes
  • Marcar um item da caixa de entrada como falso positivo

• Automações (workflows)

  • Listar automações, execuções e agendamentos
  • Obter detalhes de automações e execuções
  • Executar uma automação
  • Criar e atualizar automações e adicionar agendamentos cron

  "Automação" é o nome do produto que os usuários veem; "workflow" é o objeto Windmill subjacente usado pelos nomes da API e das ferramentas. São a mesma coisa.

• Base de conhecimento

  • Pesquisar na base de conhecimento
  • Listar coleções e documentos
  • Executar consultas estruturadas em um documento

• Painéis

  • Listar painéis e obter seus detalhes
  • Listar e obter modelos de painéis e widgets
  • Criar um painel e atualizar um existente (os campos omitidos permanecem inalterados, portanto uma pequena edição não exige o reenvio do painel inteiro)

• Integrações

  • Listar integrações externas

• RadQL (consultas avançadas)

  • Listar os tipos de dados disponíveis para consulta (containers, findings, kubernetes_resources etc.)
  • Obter esquema/metadados de tipos de dados específicos
  • Listar valores possíveis para campos de filtro
  • Executar consultas RadQL com filtragem, pesquisa e agregações
  • Criar consultas programaticamente a partir de condições estruturadas
  • Executar várias consultas em paralelo

Hospedagem própria

Prefere executar o servidor por conta própria — por exemplo, em um ambiente isolado, por requisitos de residência de dados ou para não passar pelo gateway hospedado? Ele está publicado no npm e como imagem de contêiner.

Pré-requisitos

• Node.js 20.x ou superior

Credenciais

Forneça suas credenciais do RAD Security por meio de variáveis de ambiente:

RAD_SECURITY_ACCESS_KEY_ID="your_access_key"
RAD_SECURITY_SECRET_KEY="your_secret_key"
RAD_SECURITY_ACCOUNT_ID="your_account_id"

# Optional: fetched automatically from the account if not set.
# Set this without RAD_SECURITY_ACCOUNT_ID for a session across all the tenant's accounts.
RAD_SECURITY_TENANT_ID="your_tenant_id"

# Optional: true exposes only read-only tools. Tenant-scoped sessions are read-only unless this is false.
RAD_SECURITY_READONLY="true"

npx (stdio) — por exemplo, Claude Desktop

{
  "mcpServers": {
    "rad-security": {
      "command": "npx",
      "args": ["-y", "@rad-security/mcp-server"],
      "env": {
        "RAD_SECURITY_ACCESS_KEY_ID": "<your-access-key-id>",
        "RAD_SECURITY_SECRET_KEY": "<your-secret-key>",
        "RAD_SECURITY_ACCOUNT_ID": "<your-account-id>"
      }
    }
  }
}

Docker (HTTP com streaming)

docker build -t rad-security/mcp-server .
docker run \
  -e TRANSPORT_TYPE=streamable \
  -e RAD_SECURITY_ACCESS_KEY_ID=your_access_key \
  -e RAD_SECURITY_SECRET_KEY=your_secret_key \
  -e RAD_SECURITY_ACCOUNT_ID=your_account_id \
  -p 3000:3000 \
  rad-security/mcp-server

Filtragem de toolkits

Controle quais toolkits um servidor hospedado por conta própria expõe:

• INCLUDE_TOOLKITS: lista de toolkits separados por vírgulas a incluir (somente estes são habilitados).
• EXCLUDE_TOOLKITS: lista de toolkits separados por vírgulas a excluir (todos os outros são habilitados). Ignorado se INCLUDE_TOOLKITS estiver definido.

Toolkits disponíveis: containers, clusters, audit, images, kubeobject, runtime, findings, inbox, workflows, knowledge_base, radql, dashboards, integrations. Todos são habilitados por padrão.

# Only the workflows toolkit
INCLUDE_TOOLKITS="workflows"

# Everything except runtime
EXCLUDE_TOOLKITS="runtime"

Multi-tenant (autenticação por solicitação)

MCP_AUTH_MODE controla como uma implantação HTTP com streaming autentica as solicitações recebidas — é isso que o endpoint hospedado usa:

• MCP_AUTH_MODE=env (padrão) — todas as sessões usam as credenciais de ambiente RAD_SECURITY_*. Tenant único e sem autenticação na camada HTTP, portanto não deve ser acessível por redes não confiáveis.
• MCP_AUTH_MODE=header — cada solicitação deve incluir sua própria credencial no cabeçalho Authorization (a forma Bearer <access_key_id>:<secret_key>:<account_id> acima); um cabeçalho ausente ou malformado é rejeitado com 401. Compatível somente com TRANSPORT_TYPE=streamable. RAD_SECURITY_API_URL é obtido da configuração do servidor, não de quem faz a chamada.

docker run \
  -e TRANSPORT_TYPE=streamable \
  -e MCP_AUTH_MODE=header \
  -e RAD_SECURITY_API_URL=https://api.rad.security \
  -p 3000:3000 \
  rad-security/mcp-server

O transporte SSE (TRANSPORT_TYPE=sse) está obsoleto e foi substituído por HTTP com streaming; ele usa somente credenciais de ambiente.

Desenvolvimento

# Install dependencies
npm install

# Run type checking
npm run type-check

# Run linter
npm run lint

# Build
npm run build

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes