CAST MCP Server for Gatekeeper installation on Linux via Docker

Overview

This guide covers the installation of the CAST MCP Server for Gatekeeper on Linux via Docker. It’s intended for:

• Direct installation on Linux, via Docker
• new installations (i.e. from scratch)
• in-place updates to a new release

The installation package com.castsoftware.gatekeeper.mcpserver.docker  includes an installation script (run.sh) and configuration files. All Docker images are pulled direct from https://hub.docker.com  during the installation.

What’s new?

See the release notes.

How it works

The MCP Server sits between an AI client and the CAST Imaging for Gatekeeper REST API:

1. A user types a natural-language query in their AI assistant (e.g., “Show me security violations for MyApp”).
2. The AI client (Claude / Copilot) identifies the right MCP Tool to call.
3. The MCP Server receives the structured tool call, validates inputs, and forwards the request to the API.
4. The response is normalised and returned to the AI, which presents a human-readable summary.

Requirements

The CAST MCP Server for Gatekeeper is a standalone component and can therefore be installed wherever convenient in your local environment, e.g. on a dedicated machine, or on a machine already used by other CAST Imaging components.

When using a dedicated machine, CAST recommends following the general hardware and software requirements but note that the component does not require:

• a Java JRE/JDK

Other requirements:

• MCP Server runs as a Docker container on TCP port 8283 although you can change this in the .env file (see below). You may therefore need to adjust firewall rules to allow incoming connections to this port
• see software requirements for more information about supported Linux OS, Docker Engine and Docker Compose
• a minimum of 2GB free disk space
• An MCP-aware client such as GitHub Copilot (Visual Studio Code), Claude Desktop, or Cursor
• a functioning release of CAST Imaging for Gatekeeper (Dashboards) installed (MCP Server interacts with the imaging-services component) in your network (see CAST Imaging compatibility below)
• a CAST Imaging API key, see Generating an API key

CAST Imaging compatibility

MCP-aware client connection routing

MCP-aware clients connect directly to CAST Imaging via its public gateway - instead of direct to the MCP Server. As a result, CAST Imaging 3.6.2-funcrel or later is required as the target installation to ensure proper routing back to the MCP Server. This integration ensures all query requests are routed through CAST Imaging.

HTTPS

If you require a secure HTTPS connection between your MCP-aware client and the MCP Server, you must enable HTTPS on the CAST Imaging gateway - see HTTPS configuration.

Installation process

Step 1 - Verify connection to CAST Imaging

Before proceeding, ensure you can access CAST Imaging (the imaging-services component) from the machine where you intend to install MCP Server by running the following (tailored to your own environment):

$ curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/dashboards/rest/server

The expected output is at least one entry similar to:

[
  {
    "href": "55c46218-c3f3-44ad-9042-7e1791ec7cbf",
    "name": "55c46218-c3f3-44ad-9042-7e1791ec7cbf",
    "dbType": "ADG",
    "version": "8.4.10",
    "schema": "app1_central",
    "dbmsVersion": "PostgreSQL",
    "componentsIndexStatus": "upToDate",
    "violationsIndexStatus": "toCreate",
    "systems": {
      "href": "55c46218-c3f3-44ad-9042-7e1791ec7cbf/systems",
      "name": "All Systems. A system represents a portfolio of applications."
    },
    "applications": {
      "href": "55c46218-c3f3-44ad-9042-7e1791ec7cbf/applications",
      "name": "All Applications. An application represents ..."
    },
    "nbOfApplications": 1,
    "configurations": {
      "href": "55c46218-c3f3-44ad-9042-7e1791ec7cbf/configuration/snapshots",
      "name": "All configuration snapshots ..."
    },
    "results": {
      "href": "55c46218-c3f3-44ad-9042-7e1791ec7cbf/results",
      "name": "Results by snapshots, by systems, by ..."
    },
    "commonCategories": null,
    "tags": null
  }
]

Step 2 - Download the installation media

Download the installer using curl:

$ curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.gatekeeper.mcpserver.docker/<version>?platform=linux_x64" -H "x-nuget-apikey: <api-key>" -H "accept: application/octet-stream"

Where:

• -#: enables a download progress bar.
• -O: (--remote-name) ensures the file is downloaded and saved to the current folder using the same name as the remote file.
• -J: (--remote-header-name) ensures the -O option uses the server-specified Content-Disposition filename instead of extracting a filename from the URL. If the server-provided filename contains a path, that is stripped off before the filename is used.
• <version>: use latest to download the most recent release, or specify the specific release, e.g., 1.0.1-funcrel.
• -H: (--header) defines the additional header to include in information sent.
• <api-key>: your CAST Extend API key (obtain this from https://extend.castsoftware.com/#/profile/settings )

Example for latest release:

$ curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.gatekeeper.mcpserver.docker/latest?platform=linux_x64" -H "x-nuget-apikey: a9999a9a-c999-999d-999b" -H "accept: application/octet-stream"

Unzip the resulting ZIP file anywhere on your local disk. The following files/folders will be created:

com.castsoftware.gatekeeper.mcpserver.docker.<version>/
├── config/
│   └── app.config
├── copilot-instructions.md
├── docker-compose.yml
├── README.md
├── run.sh
└── .env                        # Hidden file (use `ls -a` to view)

Step 3 - Configure your installation

app.config

Locate the config/app.config file at the root of the unzipped installation media. Open the file with a text editor and update the installation variables to match your environment:

HOST_CONTROL_PANEL=localhost                      # Required: IP address/hostname/FQDN of the machine on which the "imaging-services" component is installed. The use of "localhost" is not supported.
PORT_CONTROL_PANEL=8098                           # Default port on which the CAST Imaging Control Panel service (part of the "imaging-services" component) is running - unless you have changed this during the CAST Imaging installation, leave it as is
MCP_SERVER_PORT=8283                              # Default listening port for MCP Server
SERVICE_NAME="GatekeeperMCPServer"                # Default service name for MCP Server
SERVICE_HOST=""                                   # Required: IP address/hostname/FQDN of the machine on which the MCP Server will be installed (i.e. the current machine). Do not set as "localhost".
CONTROL_PANEL_SSL_ENABLED=false                   # When set to true, allows communication with a CAST Imaging instance which is configured to use HTTPS.
SSL_CA_BUNDLE=                                    # Sets the path to a self-signed certificate chain exported to file, typically in **Base-64 PEM** format. Only necessary where CAST Imaging is configured in HTTPS mode with SSL/TLS certificates issued by a **private** or **self-signed certificate authority** (CA).

Step 4 - Run the installation

Run the following commands:

$ chmod +x run.sh    # makes the installation script executable
$ ./run.sh           # runs the installation and makes the current folder the installation path

Verify the installation by checking Docker containers (you should see one Docker container hosting the MCP Server):

$ docker ps

Verify the health endpoint of the MCP Server:

$ curl http://<mcp-server>:8283/mcp/healthcheck

Expected response:

{
  "status": "healthy",
  "service": "mcp-server",
  "details": {
    "dashboard_client": "available",
    "dashboard_api": "configured"
  }
}

Check logs if needed:

$ docker logs <container-name>

Step 5 - Configure your MCP-aware client

All MCP-aware clients must be configured to connect directly to CAST Imaging, i.e. the machine on which the imaging-services component is installed. You should use:

• either http or https depending on whether HTTPS configuration has been enabled
• the machine’s fully qualified domain name, such as imaging.corp.mycompany.com, or its IP address
• the user access port for CAST Imaging, either 8090 (http) or 443 (https) - note that when https is running on port 443, it is not necessary to define the port
• /mcp/gatekeeper should always be appended

Examples:

http://imaging.corp.mycompany.com:8090/mcp/gatekeeper >>> unsecured URL on port 8090

https://imaging.corp.mycompany.com/mcp/gatekeeper >>> TLS/SSL secured URL on port 443

https://imaging.corp.mycompany.com:8443/mcp/gatekeeper >>> TLS/SSL secured URL on custom port 8443

VS Code with GitHub Copilot

Create .vscode/mcp.json in your project root and update to match your environment:

{
  "inputs": [
    {
      "id": "dashboard-key",
      "type": "promptString",
      "description": "CAST Imaging API Key"
    }
  ],
  "servers": {
    "gatekeeper": {
      "type": "http",
      "url": "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp/gatekeeper",
      "headers": {
        "x-api-key": "${input:dashboard-key}"
      }
    }
  }
}

VS Code will prompt for the API key when you first use the MCP server. Credentials are stored securely in VS Code’s secret storage.

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json and update to match your environment:

{
  "mcpServers": {
    "gatekeeper": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp/gatekeeper",
        "--header",
        "x-api-key:your-api-key",
        "--allow-http"
      ]
    }
  }
}

Cursor

Start the MCP Server first, then create .cursor/mcp.json and update to match your environment:

{
  "mcpServers": {
    "gatekeeper": {
      "type": "http",
      "url": "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp/gatekeeper",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}

Cursor uses HTTP transport only - the MCP server must be running before you start Cursor.

Step 6 - Test your MCP-aware client

1. Launch your MCP-aware client
2. Enter your CAST Imaging API key when prompted
3. Run a test query, for example:

Show me the compliance status for MyApp
How many days of technical debt does MyApp have?
List the top 10 security violations for MyApp

If successful (see below), you’re ready to use your MCP Client with your MCP Server.

Success indicators

✅ Connection successful if you receive:

• Compliance or quality metrics
• Violation details

❌ Check configuration if you see:

• Connection errors
• Authentication failures
• Empty application lists

Example prompts

Prompts are pre-configured workflow templates. They instruct the AI agent which tools to call, in what order, and how to format the output. Unlike tools, prompts do not call the API directly - they return instructional messages that guide the AI.

Example natural-language queries

Assess ISO-5055 compliance for MyApp

Identify security violations in MyApp snapshot 6

Calculate technical debt for MyApp

Show quality trends for MyApp across the last 3 snapshots

List violations for MyApp — guide me through the filters

Available tools

Tools are functions the AI agent can call directly. Each tool maps to one or more Dashboard REST API call.

list_applications

List all applications the current user has access to and where at least one snapshot has been generated for a given application:

Example:

• “Get application list for Gatekeeper MCP server”

get_mcp_info

Check the Gatekeeper MCP Server’s version and confirm it is compatible with your connected CAST Imaging installation. Reports the running MCP Server version, the connected CAST Imaging version, and the minimum required version.

Example natural-language queries:

• “What version of the MCP server am I running?”
• “Check if my Console is compatible with this MCP server”
• “Show me the server info”

get_compliance_status

Get compliance status - quality indicators, violation counts, and health factors for an application.

Example natural-language queries:

• “Show me the compliance status for MyApp”
• “Compare security violations between snapshot 5 and 6 for MyApp”
• “Get quality indicators for MyApp filtered by JEE technology”

get_technical_debt

Get technical debt metrics — remediation effort in minutes and equivalent 8-hour work days.

Example natural-language queries:

• “How many days of technical debt does MyApp have?”
• “Show technical debt breakdown by health factor for MyApp”
• “What is the security-related debt for MyApp in the last 3 months?”

get_violations

Get detailed violations with file paths, line numbers, rule details, and remedial actions. Supports pagination.

Example natural-language queries:

• “List the top 50 security violations added in the latest snapshot of MyApp”
• “Show me ISO-5055 violations for MyApp with source code locations”
• “Get all unchanged Robustness violations for MyApp in JEE technology”

get_objects

Get objects (classes, methods, files, etc.) for an application snapshot, sorted by name, with their violated rules.

Example natural-language queries:

• “List objects in MyApp’s latest snapshot”
• “List Java methods in MyApp’s latest snapshot with a name starting with "get"”
• “Show objects in MyApp snapshot 6 with at least one Security violation”
• “Find objects in MyApp whose file path contains "controllers"”
• “List ISO-5055 objects in MyApp, sorted by name, 50 per page”
• “Show the next page of objects, skipping the first 50”

manage_action_plan

Get, add, edit, or delete action plan issues for an application. Adding, editing, or deleting requires the QUALITY_MANAGER role.

To convert an exclusion into an action plan item, call the tool with operation="add" directly. Do not delete the exclusion first — the backend automatically removes the matching exclusion.

Example natural-language queries:

• “Show me the action plan for MyApp”
• “List pending action plan items for MyApp in snapshot 6”
• “Show high-priority action plan issues for MyApp that are still unsolved”
• “Add MyApp’s violation on component X, rule Y to the action plan with high priority and comment "fix in next sprint"”
• “Change the priority of that action plan item to medium and update the comment to "scheduled for Q3"”
• “Remove the action plan entry for component X, rule Y in MyApp”
• “Move MyApp’s excluded violation on component X, rule Y into the action plan instead”

manage_exclusion

Get, add, edit, or delete exclusion requests for an application. Adding, editing, or deleting requires the EXCLUSION_MANAGER role.

Example natural-language queries:

• “Show all active exclusions for MyApp”
• “Show scheduled exclusions for MyApp that are pending removal”
• “List every exclusion, active and scheduled, for MyApp in snapshot 6”
• “Exclude MyApp’s violation on component X, rule Y with comment "false positive, confirmed by security team"”
• “Update the exclusion comment for component X, rule Y to "re-confirmed after code review"”
• “Remove the exclusion request for component X, rule Y in MyApp”

Snapshot Syntax Reference

All tools that accept a snapshot parameter support the same flexible syntax:

ISO-5055 support

Mention “ISO-5055” in your question and the AI agent will answer using the standard’s terminology.

Terminology

Prompts to try

• “Get ISO-5055 compliance status for MyApp”
• “Show me MyApp’s ISO-5055 occurrences for the Security characteristic”
• “Get ISO-5055 violations for MyApp in snapshot 6”
• “Get ISO-5055 technical debt for MyApp, broken down by detection pattern”
• “Assess MyApp’s ISO-5055 compliance”

Troubleshooting

Common checks:

• Check the container is running:

$ docker ps

• Verify port availability:

$ netstat -tlnp | grep 8283

• Check logs:

$ docker logs <container-name>
# or
$ tail -f /app/logs/mcp_dashboard.log

• Test connectivity to the API:

$ curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/dashboards/rest/server

• If you see "DashboardClient cannot be initialized", the Control Panel is likely using HTTPS - set CONTROL_PANEL_SSL_ENABLED=true in <installer-root>/config/app.config.

CAST Imaging configured in HTTPS mode with self-signed or private certificate authority SSL/TLS certificates

If your CAST Imaging instance is configured in HTTPS mode with SSL/TLS certificates issued by a private or self-signed certificate authority (CA) - not required when you are using an authoritative CA - then you must configure the MCP Server (via the SSL_CA_BUNDLE) variable available in the app.config file with the path to the self-signed certificate chain exported to file, typically in Base-64 PEM format. To do so see the instructions below:

$ cat root.crt intermediate.crt > my_cert.pem

-----BEGIN CERTIFICATE-----
(Base64 encoded data)
-----END CERTIFICATE-----

<installer-root>/certificates/my_cert.pem

SSL_CA_BUNDLE=/app/certificates/my_cert.pem

$ docker compose down
$ ./run.sh

Updating configuration after installation

To change a configuration option (for example CONTROL_PANEL_SSL_ENABLED or PORT_CONTROL_PANEL) on an already-installed instance, you do not need to re-run the installer:

1. Open the deployed configuration file with a text editor:

<installer-root>/config/app.config

2. Change the required setting(s) and save the file.
3. Restart the MCP Server container for the change to be taken into account:

$ docker compose down
$ ./run.sh

Update process

To update to a new release of CAST Gatekeeper MCP Server:

• Download the installation media for the target release
• Unzip the installation media
• Update the config/app.config file to set the SERVICE_HOST parameter to the IP address, hostname, or FQDN of the machine where MCP Server is installed (the current machine). Important: do not set this as “localhost”
• Run the following commands:

$ docker ps
$ docker stop <container-name>

• Restart using the run script from the new installer location:

$ chmod +x run.sh    # makes the installation script executable
$ ./run.sh

What does the update do?

This process preserves your existing configuration and data while updating the Docker image and scripts, i.e. the following will occur:

• Stop the existing containers from the old installation location.
• Update the docker-compose.yml in the old installation location with the new Docker image.
• Migrate configuration parameters, preserving your existing settings and adding new ones.
• Restart the MCP Server service.

Uninstall process

Stop and remove the containers:

$ cd /path/to/installer-folder
$ docker-compose down

Optionally remove associated Docker images:

$ docker image ls | grep GateKeeper-mcp
$ docker rmi <image-id>   # only if you are sure
$ docker volume ls | grep Dashboard-mcp
$ docker volume rm <volume-name>   # only if you are sure

Then delete the installer directory:

$ rm -rf /path/to/installer-folder

FAQ

See Frequently Asked Questions.