StackRox MCP

Status: Developer Preview

This project is in active development. While functional, APIs and features may change in future releases. For feedback or issues, please open a GitHub issue.

Project Overview

StackRox MCP is a Model Context Protocol (MCP) server that provides AI assistants with access to StackRox.

Quick Start

Clone the repository:

git clone https://github.com/stackrox/stackrox-mcp.git
cd stackrox-mcp

Build the project:

make build

Run the server:

# With configuration file
./stackrox-mcp --config=examples/config-read-only.yaml

# Or using environment variables only
export STACKROX_MCP__CENTRAL__URL=central.stackrox:443
export STACKROX_MCP__TOOLS__VULNERABILITY__ENABLED=true
./stackrox-mcp

The server will start on http://0.0.0.0:8080 by default. See the Testing the MCP Server section for instructions on connecting with Claude Code.

Configuration

The StackRox MCP server supports configuration through both YAML files and environment variables. Environment variables take precedence over YAML configuration.

Configuration File

Specify a configuration file using the --config flag:

./stackrox-mcp --config=/path/to/config.yaml

See examples/config-read-only.yaml for a complete configuration example.

Environment Variables

All configuration options can be set via environment variables using the naming convention:

STACKROX_MCP__SECTION__KEY

Note the double underscore (__) separator between sections and keys.

Examples

export STACKROX_MCP__CENTRAL__URL=central.stackrox:443
export STACKROX_MCP__GLOBAL__READ_ONLY_TOOLS=true
export STACKROX_MCP__TOOLS__CONFIG_MANAGER__ENABLED=true

Configuration Options

Central Configuration

Configuration for connecting to StackRox Central.

Option	Environment Variable	Type	Required	Default	Description
central.url	STACKROX_MCP__CENTRAL__URL	string	Yes	central.stackrox:443	URL of StackRox Central instance
central.auth_type	STACKROX_MCP__CENTRAL__AUTH_TYPE	string	No	passthrough	Authentication type: passthrough (use token from MCP client headers) or static (use configured token). Note: Helm chart only supports passthrough mode.
central.api_token	STACKROX_MCP__CENTRAL__API_TOKEN	string	Conditional	-	API token for static authentication (required when auth_type is static, must not be set when passthrough)
central.insecure_skip_tls_verify	STACKROX_MCP__CENTRAL__INSECURE_SKIP_TLS_VERIFY	bool	No	false	Skip TLS certificate verification (use only for testing)
central.force_http1	STACKROX_MCP__CENTRAL__FORCE_HTTP1	bool	No	false	Route gRPC traffic through the HTTP/1 bridge (gRPC-Web/WebSockets) for environments that block HTTP/2
central.request_timeout	STACKROX_MCP__CENTRAL__REQUEST_TIMEOUT	duration	No	30s	Maximum time to wait for a single request to complete (must be positive)
central.max_retries	STACKROX_MCP__CENTRAL__MAX_RETRIES	int	No	3	Maximum number of retry attempts (must be 0-10)
central.initial_backoff	STACKROX_MCP__CENTRAL__INITIAL_BACKOFF	duration	No	1s	Initial backoff duration for retries (must be positive)
central.max_backoff	STACKROX_MCP__CENTRAL__MAX_BACKOFF	duration	No	10s	Maximum backoff duration for retries (must be positive and >= initial_backoff)

When central.force_http1 is enabled, the client uses the StackRox gRPC-over-HTTP/1 bridge to downgrade requests. This should only be turned on when Central is reached through an HTTP/1-only proxy or load balancer, as client-side streaming remains unsupported in downgrade mode.

Global Configuration

Global MCP server settings.

Option	Environment Variable	Type	Required	Default	Description
global.read_only_tools	STACKROX_MCP__GLOBAL__READ_ONLY_TOOLS	bool	No	true	Only allow read-only tools

Server Configuration

HTTP server settings for the MCP server.

Option	Environment Variable	Type	Required	Default	Description
server.type	STACKROX_MCP__SERVER__TYPE	string	No	streamable-http	Server transport type: streamable-http (HTTP server) or stdio (stdio transport). Note: stdio transport requires central.auth_type to be set to static. Helm chart only supports streamable-http.
server.address	STACKROX_MCP__SERVER__ADDRESS	string	No	0.0.0.0	HTTP server listen address (only applies when server.type is http)
server.port	STACKROX_MCP__SERVER__PORT	int	No	8080	HTTP server listen port (must be 1-65535, only applies when server.type is http)

Tools Configuration

Enable or disable individual MCP tools. At least one tool has to be enabled.

Option	Environment Variable	Type	Required	Default	Description
tools.vulnerability.enabled	STACKROX_MCP__TOOLS__VULNERABILITY__ENABLED	bool	No	false	Enable vulnerability management tools
tools.config_manager.enabled	STACKROX_MCP__TOOLS__CONFIG_MANAGER__ENABLED	bool	No	false	Enable configuration management tools

Configuration Precedence

Configuration values are loaded in the following order (later sources override earlier ones):

1. Default values
2. YAML configuration file (if provided via --config)
3. Environment variables (highest precedence)

Testing the MCP Server

Starting the Server

Start the server with a configuration file:

./stackrox-mcp --config examples/config-read-only.yaml

Or using environment variables:

export STACKROX_MCP__CENTRAL__URL="central.example.com:443"
export STACKROX_MCP__TOOLS__VULNERABILITY__ENABLED="true"
./stackrox-mcp

The server will start on http://0.0.0.0:8080 by default (configurable via server.address and server.port).

Connecting with Claude Code CLI

HTTP Transport

Add the MCP server to Claude Code using HTTP transport:

claude mcp add --transport http stackrox-mcp http://localhost:8080/mcp \
  --header "Authorization: Bearer <YOUR_STACKROX_API_TOKEN>"

Stdio Transport

Add the MCP server to Claude Code using stdio transport with static authentication:

claude mcp add --transport stdio stackrox-mcp \
  --env STACKROX_MCP__SERVER__TYPE=stdio \
  --env STACKROX_MCP__CENTRAL__AUTH_TYPE=static \
  --env STACKROX_MCP__CENTRAL__API_TOKEN="${ROX_TOKEN}" \
  --env STACKROX_MCP__CENTRAL__URL=central.stackrox:443 \
  --env STACKROX_MCP__TOOLS__CONFIG_MANAGER__ENABLED=true \
  -- /path/to/stackrox-mcp

Important: Stdio transport requires static authentication (central.auth_type=static). Passthrough authentication is not supported with stdio transport.

Verifying Connection

List configured MCP servers:

claude mcp list

Get details for a specific server:

claude mcp get stackrox-mcp

Within a Claude Code session, use the /mcp command to view available tools from connected servers.

Example Usage

Once connected, interact with the tools using natural language:

List all clusters

Can you list all the clusters secured by StackRox?

Check for a specific vulnerability (CVE)

Is CVE-2021-44228 detected in any of my clusters?

Check for GitHub Security Advisory

Is GHSA-jfh8-c2jp-5v3q detected in any of my deployments?

Check for Red Hat Security Advisory

Check if RHSA-2026:1594 is present in nodes in the production-cluster

Vulnerability analysis in specific namespace

Check if CVE-2021-44228 is present in deployments in namespace "backend"

Filter by cluster

Show me all deployments affected by CVE-2021-44228 in the dev-cluster

Container Images

Registry

Official images are published to Quay.io:

quay.io/stackrox-io/mcp

Supported Architectures

Multi-architecture images support the following platforms:

• linux/amd64 - Standard x86_64 architecture
• linux/arm64 - ARM 64-bit (Apple Silicon, AWS Graviton, etc.)
• linux/ppc64le - IBM POWER architecture
• linux/s390x - IBM Z mainframe architecture

Docker/Podman will automatically pull the correct image for your platform.

Available Tags

Tag Pattern	Description	Example
latest	Latest release version	quay.io/stackrox-io/mcp:latest
v{version}	Specific release version	quay.io/stackrox-io/mcp:v1.0.0
{commit-sha}	Specific commit from main branch	quay.io/stackrox-io/mcp:a1b2c3d

Usage

Pull Image

docker pull quay.io/stackrox-io/mcp:latest
# or
podman pull quay.io/stackrox-io/mcp:latest

Run Container

docker run -p 8080:8080 \
  --env STACKROX_MCP__CENTRAL__URL=central.stackrox:443 \
  --env STACKROX_MCP__TOOLS__CONFIG_MANAGER__ENABLED=true \
  quay.io/stackrox-io/mcp:latest

Building Images Locally

Build a single-platform image:

VERSION=dev make image

Build Arguments

• TARGETOS - Target operating system (default: linux)
• TARGETARCH - Target architecture (default: amd64)
• VERSION - Application version (default: auto-detected from git)

Image Details

• Base Image: Red Hat UBI10-micro (minimal, secure)
• User: Non-root user (UID/GID 4000)
• Port: 8080
• Health Check: Built-in health endpoint at /health

Automated Builds

Images are automatically built and pushed on:

• Main branch commits: Tagged with commit SHA
• Version tags: Tagged with version number and latest

See .github/workflows/build.yml for build pipeline details.

Kubernetes Deployment

Deploy the StackRox MCP server to Kubernetes or OpenShift clusters using Helm.

For Kubernetes/OpenShift deployments, see the Helm Chart README for complete configuration options, authentication details, and deployment examples.

Prerequisites

• Kubernetes 1.19+ or OpenShift 4.x+
• Helm 3.0+
• Access to a StackRox Central instance

Installing with Helm

Basic installation:

helm install stackrox-mcp charts/stackrox-mcp \
  --namespace stackrox-mcp \
  --create-namespace \
  --set-file tlsSecret.cert=/path/to/tls.crt \
  --set-file tlsSecret.key=/path/to/tls.key \
  --set-file openshift.route.tls.destinationCACertificate=/path/to/tls.crt \
  --set config.central.url=central.stackrox:443

With custom values file:

Create a values.yaml file:

config:
  central:
    url: "central.example.com:443"

Install with custom values:

helm install stackrox-mcp charts/stackrox-mcp \
  --namespace stackrox-mcp \
  --create-namespace \
  --set-file tlsSecret.cert=/path/to/tls.crt \
  --set-file tlsSecret.key=/path/to/tls.key \
  --set-file openshift.route.tls.destinationCACertificate=/path/to/tls.crt \
  --values values.yaml

OpenShift deployment with Route:

helm install stackrox-mcp charts/stackrox-mcp \
  --namespace stackrox-mcp \
  --create-namespace \
  --set config.central.url=central.stackrox:443 \
  --set-file tlsSecret.cert=/path/to/tls.crt \
  --set-file tlsSecret.key=/path/to/tls.key \
  --set-file openshift.route.tls.destinationCACertificate=/path/to/tls.crt \
  --set openshift.route.host=stackrox-mcp.apps.example.com

Important Notes for Helm Deployments:

• The Helm chart uses passthrough authentication only (central.auth_type=passthrough). Clients must provide API tokens.
• The Helm chart uses streamable-http transport only (server.type=streamable-http). Stdio transport is not supported in Kubernetes.
• See the Helm Chart README for details on authentication configuration, TLS setup, and advanced options.

Managing the Deployment

Upgrade an existing release:

helm upgrade stackrox-mcp charts/stackrox-mcp \
  --namespace stackrox-mcp \
  --reuse-values

Uninstall:

helm uninstall stackrox-mcp --namespace stackrox-mcp

Configuration

For complete configuration options including:

• Security contexts and pod security standards
• Resource limits and requests
• High availability setup
• OpenShift-specific configuration

See the Helm Chart README.

Integrations

OpenShift Lightspeed Integration:

For integrating StackRox MCP with OpenShift Lightspeed, see the OpenShift Lightspeed Integration Guide.

Development

For detailed development guidelines, testing standards, and contribution workflows, see CONTRIBUTING.md.

Quick Reference

View all available commands:

make help

Common commands:

• make build - Build the binary
• make test - Run tests
• make fmt - Format code
• make lint - Run linter

Code Style Checks

The project enforces several code style checks:

• Go formatting: make fmt-check (or make fmt to auto-fix)
• Go linting: make lint
• Shell scripts: make shell-lint
• GitHub Actions workflows: make actionlint
• Dockerfile: make dockerfile-lint
• Helm charts: make helm-lint

All checks run automatically in CI on pull requests.

Shell Script Guidelines

• All scripts must pass shellcheck with no errors
• Use set -e for error handling
• Use SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" for directory detection
• Include cleanup traps for temporary resources (see existing scripts for examples)