CAST MCP Server for Gatekeeper installation on Microsoft Windows

Overview

This guide covers the installation of the CAST MCP Server for Gatekeeper on Microsoft Windows. It’s intended for:

• Direct installation on Microsoft Windows
• new installations (i.e. from scratch)
• in-place updates to a new release

The installation package com.castsoftware.gatekeeper.mcpserver  includes an installation script (.bat file), various configuration files and the binaries themselves.

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 be installed wherever convenient in your 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 Microsoft Windows service on TCP port 8283 (configurable). You may need to adjust firewall rules to allow incoming connections to this port.
• see software requirements for more information about supported Microsoft Windows OS versions
• 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/

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 latest release of the installer (com.castsoftware.gatekeeper.mcpserver ) and unzip it anywhere on your local disk. The following files/folders will be created:

com.castsoftware.gatekeeper.mcpserver.<version>/
├── gatekeeper-mcpserver
├── tools
├── configuration.conf
├── copilot-instructions.md
├── mcp-server-installer.bat
├── README.md

Step 3 - Configure your installation

Locate the configuration.conf 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 CAST Imaging "imaging-services" component is installed. You can use localhost if MCP Server is installed on the same machine as the "imaging-services" component
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 MCP server listening port, default is 8283 if not specified
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.

Step 4 - Run the installation

Open a CMD window with elevated permissions (right click, Run as administrator) and execute the following command from the root of the unzipped files:

mcp-server-installer.bat --install configuration.conf

Wait for the installation process to complete. On completion, check that a Microsoft Windows service named GatekeeperMCPServer has been created and is up and running.

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"
  }
}

Step 5 - Configure your MCP-aware client

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 Dashboard API Key"
    }
  ],
  "servers": {
    "dashboard": {
      "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": {
    "dashboard": {
      "url": "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp/gatekeeper",
      "headers": {
        "x-api-key": "your-api-key"
      }
    }
  }
}

Cursor

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

{
  "mcpServers": {
    "dashboard": {
      "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/if prompted
3. Run a test query, for example:

What applications are available?

or:

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

Success indicators

✅ Connection successful if you receive:

• Valid application listings
• 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.

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”

Snapshot Syntax Reference

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

Troubleshooting

Common checks:

1. Verify the Windows service GatekeeperMCPServer is running — restart it if required.
2. Check the MCP Server health endpoint: http://<mcp-server>:8283/mcp/healthcheck
3. Check logs at %PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\logs\mcp_gatekeeper.log
4. Test connectivity to the API:

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

1. If you see "DashboardClient cannot be initialized", the Control Panel is likely using HTTPS - set CONTROL_PANEL_SSL_ENABLED=true.

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
• Open a Command Prompt with administrative privileges (right click, Run as administrator)
• Navigate to the extracted directory of the newly downloaded installer, and run:

mcp-server-installer.bat --update

Wait for the update to complete.

Uninstall process

Open a Command Prompt with administrative privileges (right click, Run as administrator), navigate to the extracted installer directory, and run:

mcp-server-installer.bat --uninstall

FAQ

See Frequently Asked Questions.