Update and troubleshoot the CAST MCP Servers

Update, reconfigure, uninstall and troubleshoot the CAST Imaging and CAST Gatekeeper MCP Servers on Microsoft Windows and Linux via Docker

Overview

This page is for administrators who have installed a CAST MCP Server with the CAST Imaging or CAST Gatekeeper installation instructions. Select the tab matching your platform in each section.

Update the CAST Imaging MCP Server

The installation media includes a dedicated update option that performs an in-place update to this release:

  • Ensure your target CAST Imaging release meets the minimum for this MCP Server release - see CAST Imaging compatibility
  • Download the installation media for the target release
  • Unzip the installation media
  • Update the configuration.conf 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 leave this set as “localhost”
  • Set NEO4J_URL in the configuration.conf file, unless the semantic search and Text2Cypher MCP servers are being left disabled
  • Open a CMD window with elevated permissions (right click, Run as administrator)
  • Navigate to the root directory of the unzipped files and run:
mcp-server-installer.bat --update

What does the update do?

The update stops the service, checks that the ports are free, replaces the programs, restarts the service and health-checks the endpoint and every enabled MCP server behind it. It fails rather than reporting success if any of them does not come back.

Your settings are kept: existing values in the deployed app.config file are left alone and only settings new to the release are added. The one exception is the tool surface: STRUCTURAL_MCP_TOOL_SURFACE_PROFILE and SEMANTIC_MCP_TOOL_SURFACE_PROFILE are always set to intents, whatever the installation used before. A bare --update keeps the ports the installation already has. To change ports as part of the update - and have the installer check that they are free first - edit configuration.conf and pass it to the update instead:

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

Post-update action items

  • No client reconfiguration is required: your MCP-aware clients continue to connect to CAST Imaging exactly as before.
  • If MCP Server is installed on a different machine from CAST Imaging, open TCP port 8285 in your firewall rules so that it is reachable from the machines hosting imaging-services and imaging-viewer - see Ports. Block it from every other machine, client machines included, even when MCP Server runs on the same machine as CAST Imaging: the gateway does not check the API key.
  • STRUCTURAL_MCP_TOOL_SURFACE_PROFILE and SEMANTIC_MCP_TOOL_SURFACE_PROFILE are both set to intents in the deployed app.config file, whatever your previous value. To continue exposing all tools directly, set both to full and restart the service.
  • TELEMETRY_ENABLED and TELEMETRY_PUSH_ENABLED no longer have any effect. To stop telemetry for a tenant, clear Allow CAST to automatically collect anonymous statistical data in CAST Imaging.
  • Confirm the deployment is healthy by running mcpserver_syncronization.bat from an elevated prompt - see Step 4 - Run the installation.

The installation media includes a dedicated update option that performs an in-place update to this release:

  • Ensure your target CAST Imaging release meets the minimum for this MCP Server release - see CAST Imaging compatibility
  • Download the installation media for the target release
  • Unzip the installation media next to, not over, the existing installation
  • Set NEO4J_URL in the new .env file before you run the update - this setting is now required and cannot be carried over when the existing installation did not define it
  • Set SERVICE_HOST in the new .env file 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:
$ chmod +x run.sh                             # makes the installation script executable
$ ./run.sh --update /path/to/old/installer    # run the installation script and update the existing installation

What does the update do?

  • Validates the new installation media and pulls the new container image before anything is stopped.
  • Archives your existing docker-compose.yml, .env, config/app.config, run.sh and README.md under <old installer>/backups/pre-mcp-suite-<timestamp>/. This copy exists only for the rollback and is deleted once the update succeeds.
  • Builds a new .env from this release’s template and carries your existing settings across, including those which have been renamed - see the table below.
  • Stops the old container and installs the new files in the existing installation folder.
  • Starts the new container and waits for the gateway and every enabled MCP server to become ready.
  • Rolls back if the startup fails: the new container is stopped, the archived files are restored, any moved telemetry is put back, and your previous container image is started again. The previous image is never deleted, so a rollback always has something to return to.

Settings renamed by the update

Old setting New setting
MCP_SERVER_PORT MCP_SERVER_PORT - retained for the container-internal structural MCP port. The gateway, semantic search and Text2Cypher use 8285, 8287 and 8289
MCP_TOOL_SURFACE_PROFILE Not carried over. STRUCTURAL_MCP_TOOL_SURFACE_PROFILE and SEMANTIC_MCP_TOOL_SURFACE_PROFILE are always set to intents
MCP_INTENTS_HIDDEN_FUNCTIONS STRUCTURAL_MCP_INTENTS_HIDDEN_FUNCTIONS and SEMANTIC_MCP_INTENTS_HIDDEN_FUNCTIONS
GRAPHRAG_ENABLED=false SEMANTIC_MCP_ENABLED=false
DEBUG_MODE=true LOG_LEVEL=DEBUG
SSL_CA_BUNDLE SSL_CA_BUNDLE - the path is remapped from /app/certificates to /opt/cast/mcp-suite/certificates
AI_PROVIDER, AI_EMBEDDING_MODEL, AI_API_KEY and related settings Dropped. Semantic search reads the embedding configuration from the tenant record in Neo4j
TELEMETRY_LOCAL_FILE TELEMETRY_LOCAL_FILE - an earlier default path is moved to logs/telemetry/telemetry.jsonl, together with its rotated files and tenant sub-folders. If any file cannot be moved, all of them stay where they were and the old path is kept
TELEMETRY_ENABLED, TELEMETRY_PUSH_ENABLED Dropped, whatever their old values. Telemetry follows each tenant’s CAST Imaging setting instead

Your old config/app.config file is no longer read by anything: its settings are migrated into .env. A successful update deletes the backup folder, so the old file is not kept.

Post-update action items

  • No client reconfiguration is required: your MCP-aware clients continue to connect to CAST Imaging exactly as before.
  • If MCP Server is installed on a different machine from CAST Imaging, open TCP port 8285 in your firewall rules so that it is reachable from the machines hosting imaging-services and imaging-viewer - see Ports. Block it from every other machine, client machines included, even when MCP Server runs on the same machine as CAST Imaging: the gateway does not check the API key.
  • STRUCTURAL_MCP_TOOL_SURFACE_PROFILE and SEMANTIC_MCP_TOOL_SURFACE_PROFILE are both set to intents in the deployed .env file, whatever your previous MCP_TOOL_SURFACE_PROFILE value. To continue exposing all tools directly, set both to full and restart the MCP Server with ./run.sh --restart.
  • Any TELEMETRY_ENABLED or TELEMETRY_PUSH_ENABLED value you set before is dropped. To stop telemetry for a tenant, clear Allow CAST to automatically collect anonymous statistical data in CAST Imaging.

Update the CAST Gatekeeper MCP Server

  1. Download and unzip the installation media for the target release.
  2. Open a Command Prompt with administrative privileges (right click, Run as administrator).
  3. Navigate to the extracted directory of the newly downloaded installer, and run:
mcp-server-installer.bat --update

Wait for the update to complete. The update replaces the MCP Server executable, adds any new settings to the existing configuration, and moves log files left by earlier releases in %PROGRAMFILES%\CAST\Gatekeeper-MCP-Server\logs to %PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\logs.

  1. Download and unzip the installation media for the target release.
  2. 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.
  3. Run the following commands from the new installer folder:
$ chmod +x run.sh                             # makes the installation script executable
$ ./run.sh --update /path/to/old/installer    # updates the existing installation

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.
  • Remove legacy HTTPS components if present, and the HTTPS_ENABLED setting.
  • Migrate configuration parameters, preserving your existing settings and adding new ones.
  • Update the run.sh script in the old installation location.
  • Restart the MCP Server from the old installation location.

The installation remains in the old installer folder: make all later configuration changes there.

Change the configuration after installation

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

  1. Open the deployed configuration file with a text editor:
%PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config
  1. Change the required setting(s) and save the file.
  2. Restart the service with stop-service.bat and start-service.bat - see Managing the Windows service.

To change a configuration option (for example IMAGING_CODE or LOG_LEVEL) 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>/.env
  1. Change the required setting(s) and save the file.
  2. Apply the change:
$ ./run.sh --restart

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:
%PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\setup-config\app.config
  1. Change the required setting(s) and save the file.
  2. Restart the CAST Gatekeeper MCP Server Windows service (service name Gatekeeper-MCP-Server) using the Windows Service manager for the change to be taken into account.

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 - to change the listening port, edit <installer-root>/.env instead, as its value takes priority:
<installer-root>/config/app.config
  1. Change the required setting(s) and save the file.
  2. Restart the MCP Server container for the change to be taken into account:
$ docker compose down
$ ./run.sh

Uninstall

The installation media contains a dedicated uninstall option: to run it, 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 --uninstall

To remove only MCP Server related items:

  • stop and remove the container
  • delete the installer ZIP file
  • delete the unzipped installation files/folder
$ cd /<unzipped-install-files>
$ ./run.sh --stop

# Remove images
$ docker images | grep $servicename | awk '{print $3}' | xargs -I {} docker rmi -f {}
$ docker image prune

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

Stop and remove the container:

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

Optionally remove the Docker image:

$ docker images | grep gatekeeper-mcp-server
$ docker rmi <image-id>   # only if you are sure

Then delete the installer folder, which also holds the logs:

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

Troubleshooting

CAST Imaging MCP Server

Symptom Resolution
The service will not start Read %CONFIG_DIR%\logs\mcp_server.log. An MCP server’s console.log holds what it printed before its own logging started, which is where a bad Control Panel or Neo4j setting shows up
An MCP server’s tools do not appear Check /mcp/status and /mcp/servers - the latter shows whether each MCP server is enabled and healthy and how many tools it exposes (see HTTP endpoints) - then that MCP server’s service.log. An MCP server which was still starting when the gateway started needs a restart to be picked up - see Managing the Windows service
The service keeps restarting The Microsoft Windows Event Log, source nssm, records the restarts
Semantic search or natural-language answers fail, structural answers work Check NEO4J_URL, NEO4J_USER and NEO4J_PASSWORD in the deployed app.config file
An MCP server is missing from /mcp/status after a port change The port is already held by something else, so the MCP server could not bind. See Changing a port after the installation
Empty responses The CAST Imaging APIs are unreachable. Recheck HOSTNAME_CONTROL_PANEL and PORT_CONTROL_PANEL in the deployed app.config file

Validate the deployed configuration file at %CONFIG_DIR%\setup-config\app.config - the gateway and all three MCP servers read that one file.

Also check that the "url" parameter in the client mcp.json points to the correct URL, and regenerate your API key in the CAST Imaging profile if necessary. Each user has only one key: generating a new one invalidates the previous key, so update every client and script that used it.

To test connectivity to the CAST Imaging API:

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

Start with the status and log commands, which name the failing component:

$ ./run.sh --status
$ ./run.sh --logs
Symptom Likely cause Resolution
./run.sh --install reports “never became ready” An MCP server could not start Run ./run.sh --logs, then check logs/<component>/service.log
ECONNREFUSED in the client The container is not running Run ./run.sh --status, then ./run.sh --start
The client sees no tools The gateway started before the MCP servers were reachable Run ./run.sh --restart, then ./run.sh --status
The client sees some tools but not those of one MCP server That MCP server is disabled or unhealthy Open http://<SERVICE_HOST>:<MCP_GATEWAY_PORT>/mcp/servers, which shows whether each MCP server is enabled and healthy and how many tools it exposes - see HTTP endpoints
Semantic search or natural-language answers fail, structural answers work Neo4j is unreachable, or the credentials are wrong Check NEO4J_URL, NEO4J_USER and NEO4J_PASSWORD in the .env file
Empty responses The CAST Imaging APIs are unreachable Recheck HOST_CONTROL_PANEL and PORT_CONTROL_PANEL in the .env file. On Kubernetes, also check HOST_AUTH_SERVICE - see CAST Imaging on Kubernetes
Permission errors on logs/ after changing user The folders are owned by a different UID Run run.sh as the user which owns the installation folder

Also check that the "url" parameter in the client mcp.json points to the correct URL, and regenerate your API key in the CAST Imaging profile if necessary. Each user has only one key: generating a new one invalidates the previous key, so update every client and script that used it.

To test connectivity to the CAST Imaging API:

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

CAST Gatekeeper MCP Server

Check that the MCP Server is running with its health check endpoint:

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

Expected response:

{"status": "healthy", "service": "GatekeeperMCPServer"}

Log files rotate, with 30 gzipped files of 10 MB each. Common issues:

Symptom Likely cause Fix
"Dashboard API is not available" Wrong HOST_CONTROL_PANEL Check network connectivity and host/port settings
"DashboardClient cannot be initialized - control panel returned no configuration" Wrong HOST_CONTROL_PANEL or PORT_CONTROL_PANEL, or the Control Panel uses HTTPS Check the host and port settings. If the Control Panel uses HTTPS, set CONTROL_PANEL_SSL_ENABLED=true in app.config
404 errors on API calls Wrong API path configuration Verify HOST_CONTROL_PANEL and PORT_CONTROL_PANEL values
HTTP 429 Too Many Requests Rate limit exceeded Wait for the window to reset

Platform-specific checks:

  • Verify the Windows service CAST Gatekeeper MCP Server (service name Gatekeeper-MCP-Server) is running - restart it if required.
  • Check the MCP Server health endpoint: http://<mcp-server>:8283/mcp/healthcheck
  • Check logs at %PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\logs\mcp_gatekeeper.log
  • Test connectivity to the API:
$ curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/dashboards/rest/
  • Check the container, named gatekeeper-mcp-server, is running:
$ docker ps
  • Verify port availability:
$ netstat -tlnp | grep 8283
  • Check logs:
$ docker logs gatekeeper-mcp-server
# or
$ tail -f <installer-root>/logs/mcp_gatekeeper.log
  • Test connectivity to the API:
$ curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/dashboards/rest/server

HTTPS with self-signed or private CA 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), you must point the MCP Server to the certificate chain exported to file, typically in Base-64 PEM format, using the SSL_CA_BUNDLE setting. This is not required when you are using an authoritative CA.

  1. Export the CA certificates from your browser. In Google Chrome, click the padlock on your CAST Imaging URL → Connection is secure → Certificate is valid → Details tab. You will see a certificate hierarchy with up to three levels (root, intermediate, server). Export each CA certificate (root and intermediate - the server certificate is not required) individually, choosing Base64-encoded ASCII format and saving with a .crt extension.
  2. Combine them into a single PEM file. If you have both a root and an intermediate certificate, combine them into a single PEM file - see the commands below. If you only have a root certificate, rename it with a .pem extension.
  3. Verify the PEM file. Open the file in a text editor and confirm it contains one or more blocks in this format:
-----BEGIN CERTIFICATE-----
(Base64 encoded data)
-----END CERTIFICATE-----
  1. Move the PEM file, configure and restart the MCP Server as described for your platform:

Combine the certificates using CMD:

copy /b root.crt + intermediate.crt my_cert.pem

or PowerShell:

Get-Content root.crt, intermediate.crt | Set-Content my_cert.pem

Place the PEM file inside the certificates folder at the root of the installation. The folder is created automatically during the installation; if not, create it manually:

%PROGRAMDATA%\CAST\Imaging-MCP-Server\certificates\my_cert.pem        (CAST Imaging MCP Server)
%PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\certificates\my_cert.pem     (CAST Gatekeeper MCP Server)

Open setup-config\app.config in the same installation folder (%PROGRAMDATA%\CAST\Imaging-MCP-Server\ or %PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\) and add the following line pointing to the PEM file, for example:

SSL_CA_BUNDLE=C:\ProgramData\CAST\Imaging-MCP-Server\certificates\my_cert.pem

For CAST Gatekeeper, the installer does not create the certificates folder: create it yourself. SSL_CA_BUNDLE is already present in its app.config file: set the existing line rather than adding a new one.

Restart the MCP Server to ensure the setting is taken into account - for CAST Imaging, see Managing the Windows service; for CAST Gatekeeper, use the Windows Service manager.

Combine the certificates:

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

Place the PEM file inside a certificates folder at the root of the installer (the same directory as run.sh). The folder is created automatically by run.sh; if not, create it manually:

<installer-root>/certificates/my_cert.pem

Open <installer-root>/.env and add the following line, using the in-container path:

SSL_CA_BUNDLE=/opt/cast/mcp-suite/certificates/my_cert.pem

Restart the MCP Server to ensure the setting is taken into account:

$ ./run.sh --restart

Combine the certificates:

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

Create a certificates folder at the root of the installer (the same directory as run.sh) and place the PEM file inside it:

<installer-root>/certificates/my_cert.pem

The Gatekeeper MCP Server container does not mount this folder by default. Open <installer-root>/docker-compose.yml and add the following line to the volumes list of the mcp-server service:

      - ./certificates:/app/certificates:ro

Open <installer-root>/config/app.config and set SSL_CA_BUNDLE using the in-container path:

SSL_CA_BUNDLE=/app/certificates/my_cert.pem

Restart the MCP Server to ensure the setting is taken into account:

$ docker compose down
$ ./run.sh