CAST HIGHLIGHT MCP Server - Getting started with CAST Highlight MCP Server

Follow
Check out the latest release notes for the MCP Server at MCP Server release notes.

Getting Started With CAST Highlight MCP

The CAST Highlight MCP Server allows AI agents such as Claude, Gemini, GPT, and Codex to interact with a Highlight portfolio through the Model Context Protocol (MCP). It enables natural-language querying of Highlight data such as applications, technologies, vulnerabilities, segmentations, and scans without exposing sensitive information.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Environment Setup
  4. Deployment Modes
    4.1 Docker
    4.2 Windows Service
  5. Connecting Your AI Client
  6. Add Context to Agents
    6.1 OpenAI Codex CLI
    6.2 Gemini CLI
  7. Testing the MCP Server
  8. Tools Exposed by the MCP Server
  9. Data Safety and Security
  10. Limitations
  11. FAQ

1. Overview

The Highlight MCP Server provides a unified interface that translates AI requests into secure Highlight API calls.
It is delivered as a Docker-based service, with pre-configured support for multiple AI agents such as Gemini and Codex.

Typical capabilities include:

  • Listing and exploring Highlight applications
  • Retrieving metrics, technologies, frameworks, and vulnerabilities
  • Fetching portfolio recommendations and segmentation files
  • Monitoring or triggering scans
  • Enriching LLM responses using shared resources

All data exchanged comes only from the Highlight REST API and never includes source code or sensitive files.

2. Prerequisites

Before starting, ensure you have:

  • Docker Engine or Docker Desktop for the Docker deployment
  • Windows PowerShell as Administrator for the Windows service deployment
  • Internet access
  • A running CAST Highlight API
  • A CAST Highlight API key
  • An available port, by default 5185

3. Environment Setup

3.1 Docker

The project centralizes all configuration parameters inside .env.

cp .env.example .env

Edit the .env file:

HIGHLIGHT_API_TOKEN=__your_cast_highlight_token_here__
HIGHLIGHT_DOMAIN=__your_cast_highlight_company_id_or_domain_id_here__
HIGHLIGHT_API_BASE=__your_highlight_api_base__

# MCP transport configuration (optional)
MCP_TRANSPORT=streamable-http
MCP_SERVER_HOST=0.0.0.0
MCP_SERVER_PORT=5185
MCP_PREFIX=/mcp

All services, MCP server and AI agents, will automatically load these values.

Example HIGHLIGHT_API_BASE:

https://your-hl-server.com/WS2/

3.2 Windows Service

The project centralizes all configuration parameters inside the following files:

  • packaging/config/app.env.sample
  • packaging/config/secrets.env.sample

If you want to modify optional configuration before launching the Windows service script creation, edit those samples first.

4. Deployment Modes

4.1 Docker

Use this mode if you want a containerized runtime.

From the repository root:

cd mcp-server\docker
docker compose up -d

What this does:

  • starts the highlight-mcp-server container
  • loads variables from mcp-server/docker/.env
  • mounts persistent data volumes for logs, caches, exports, imports, zips, sources, and results

The default service listens on port 5185.

Health check:

curl http://localhost:5185/rest/ready/

Useful commands:

docker ps
docker logs -f mcp-server-highlight
docker compose down

Resource limits are defined in mcp-server/docker/docker-compose.yml:

  • mem_limit: 2g
  • memswap_limit: 2g
  • cpus: 2.0
  • pids_limit: 256

These limits help:

  • avoid saturating the Highlight API
  • protect the host server from resource exhaustion
  • keep behavior predictable under load

Adjusting limits for your environment: depending on the target server, you may want to adjust these values in docker-compose.yml.

Examples:

Small or shared server:

mem_limit: 1g
cpus: 1.0

High-capacity server:

mem_limit: 4g
cpus: 4.0

Best practices:

  • Size these limits based on host capacity, expected concurrency, and workload patterns.
  • Avoid removing limits unless the MCP server runs on a dedicated machine.

4.2 Windows Service

Use this mode if you want the MCP server installed as a native Windows service.

Open PowerShell as Administrator and run:

.\mcp-server\windows-service\scripts\Install-McpServerHighlightService.ps1

The installer asks for:

  1. Highlight API base URL
  2. Highlight domain
  3. Highlight API token

Important notes:

  • the API URL should end with a trailing slash, for example https://example.casthighlight.com/WS2/
  • if you leave the token empty, the service is installed but not started
  • for unattended installs, pass the values as parameters

Example:

.\mcp-server\windows-service\scripts\Install-McpServerHighlightService.ps1 `
  -HighlightApiBase "https://example.casthighlight.com/WS2/" `
  -HighlightDomain "my-domain" `
  -HighlightApiToken "your-token"

The installer writes the main configuration here:

C:\ProgramData\CAST\mcp-server-highlight\config\app.env
C:\ProgramData\CAST\mcp-server-highlight\config\secrets.env

If you prefer to prepare the files manually, use the samples in mcp-server/windows-service/config.

Check the service:

Get-Service mcp-server-highlight

If needed, start it after updating secrets.env:

Start-Service mcp-server-highlight

Health check:

.\mcp-server\windows-service\scripts\Test-McpServerHighlightHealth.ps1 -Port 5185

Uninstall options:

.\mcp-server\windows-service\scripts\Uninstall-McpServerHighlightService.ps1
.\mcp-server\windows-service\scripts\Uninstall-McpServerHighlightService.ps1 -RemoveInstallRoot
.\mcp-server\windows-service\scripts\Uninstall-McpServerHighlightService.ps1 -RemoveInstallRoot -RemoveDataRoot

5. Connecting Your AI Client

Any MCP-compatible AI client can interact with the Highlight MCP Server.

Below is the standard configuration structure used by agents, current case Codex, which can be placed in the root folder of your agent, for example User/.codex/config.toml:

[mcp_servers."mcp-server-highlight"]
url = "http://YourServerIp:Port/mcp" # Port by default 5185
trust = true
startup_timeout_sec = 30
tool_timeout_sec = 30

http_headers = {
  Accept = "application/json, */*;q=0.1",
  highlight_domain = "HIGHLIGHT_DOMAIN",
  highlight_api_key = "HIGHLIGHT_API_TOKEN"
}

The MCP server is multi-domain, so you can pass any domain and token pair through the headers. It overrides the global parameters:

  • HIGHLIGHT_API_TOKEN
  • HIGHLIGHT_DOMAIN

5.1 Agent Configurations

Three agent configurations are included and pre-linked to the MCP server.

Agent Config Path Description Documentation
Gemini agents/gemini/settings.json Local or Docker-based configuration for Gemini CLI https://geminicli.com/docs/tools/mcp-server/
Codex agents/codex/config.toml TOML configuration for Codex agent https://developers.openai.com/codex/mcp
Copilot agents/copilot/mcp.json JSON configuration for Copilot agent https://code.visualstudio.com/docs/copilot/customization/mcp-servers

These configurations are automatically recognized by the MCP server when active in the same Docker network.

6. Add Context to Agents

To ensure AI agents correctly understand the Highlight MCP business domain, a structured context must be provided.

All context files are located in:

agents/context/

6.1 OpenAI Codex CLI

Required file:

agents/context/AGENTS.md

Codex reads persistent context from a Markdown file.

You can directly copy the file under your Codex root folder, for example User/.codex/.

Restart Codex normally and the Highlight context will be taken into account.

6.2 Gemini CLI

Gemini supports structured system instruction injection via JSON.

Required file:

agents/context/AIAssistant-context.json

Option A, direct flag:

gemini --system-instruction-file=hl-mcp-package/agents/ressources/AIAssistant-context.json

Option B, environment variable:

export GEMINI_SYSTEM_PROMPT="$(cat hl-mcp-package/agents/ressources/AIAssistant-context.json)"

7. Testing the MCP Server

You can now interact with Highlight using natural language:

  • Test 1: List all applications
    • "List all Highlight applications available for my account."
  • Test 2: Retrieve application details
    • "Show me key metrics, technologies, and vulnerabilities for the application X."
  • Test 3: Portfolio insights
    • "What are the portfolio recommendations and why are they important?"

Warning: list_applications and some other tools might take a bit of time to load depending on the size of your portfolio.

8. Tools Exposed by the MCP Server

The MCP server exposes read-only tools for exploring Highlight data, including:

  • application listing and search
  • application details and results
  • alerts and vulnerabilities
  • cloud readiness and recommendations
  • components, frameworks, and licenses
  • benchmarks and segmentation

9. Data Safety and Security

The Highlight MCP Server strictly respects data-privacy constraints.

The MCP returns only Highlight API data:

  • Application metadata
  • Technology detections
  • Vulnerability summaries
  • Segmentation files
  • Scanning logs

It never returns:

  • Source code
  • Credentials
  • User data
  • Repository contents
  • Local file system access

Authentication is handled via your .env values: highlight_api_key and highlight_domain.

No authentication is ever forwarded to AI agents or stored in clear text outside the container.

10. Limitations

Warning: No access to source code or repository content.

The MCP only exposes REST API metadata. It does not read or return file contents.

Warning: No write operations on portfolio data.

The MCP cannot modify or delete applications, metrics, or metadata.

Warning: Dependent on API key permissions.

The MCP can only return data permitted by the associated API key. Permissions are inherited from the Highlight account.

Warning: Limited by API performance and rate limits.

Large portfolios or heavy operations may cause slower responses or temporary latency.

Warning: JSON may be large.

Some JSON results depending on your portfolio size might be large. Currently the MCP server has a max limit of 512 MB per API response.

Warning: AI models may hallucinate interpretations.

Although tools deliver structured data, the AI's explanations or conclusions may vary depending on the model's reasoning abilities.

11. FAQ

General

Q: What is the Highlight MCP Server?

It is an HTTP-based service that allows AI assistants to interact with portfolio and application metadata through a set of predefined tools.

Q: Do I need to install anything on my machine?

Only Docker is required. The MCP server runs as a container via Docker Compose.

Q: Which AI assistants are compatible?

Any assistant that supports the Model Context Protocol (MCP), including tools integrating Gemini, Codex, and others.

Authentication

Q: How do I authenticate with the MCP server?

You provide your platform API key and domain in the .env file. AI clients forward these values as headers when calling the MCP.

Q: Is my API key exposed to the AI model?

No. The API key is passed as an HTTP header to the MCP backend, not to the language model.

Data Privacy

Q: What information is sent to the AI model?

Only REST API metadata: application names, metrics, technologies, vulnerabilities, segmentation summaries, and scan logs.

Q: Is source code ever sent to the AI?

Never. The MCP server does not access or return source files.

Q: Can the MCP modify or delete portfolio data?

No. All MCP tools are read-only except scan operations, which only create new scan results.

Technical

Q: My MCP server does not start. What should I check?

  • Verify the .env file is present and correctly filled in.
  • Make sure no other service uses port 5185.
  • Check container logs using docker logs -f mcp-server-highlight.

Q: The AI assistant says the MCP server is unreachable.

Verify that:

  • the container is running
  • the MCP URL matches http://127.0.0.1:5185/mcp/
  • your AI client was restarted after configuration changes

Q: Why do some responses take several seconds?

  • Large portfolios
  • Heavy queries such as segmentation, vulnerabilities, and scan logs
  • API latency

Q: Why do I get an authentication error?

  • Invalid API key
  • Domain mismatch
  • Missing or incorrect environment variables
Have more questions? Submit a request

Comments

Powered by Zendesk