Update and troubleshoot the CAST MCP Servers
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.
- This page covers CAST Imaging MCP Server 3.1.0-funcrel or later. For 3.0.x, see the update, troubleshooting and uninstall sections of MCP Server 3.0.x installation on Microsoft Windows or on Linux via Docker.
- For Podman and air-gapped installations (3.0.x), see the troubleshooting sections of Installation on Linux via Podman and Installation in an air-gapped environment.
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.conffile to set theSERVICE_HOSTparameter 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_URLin theconfiguration.conffile, 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-servicesandimaging-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_PROFILEandSEMANTIC_MCP_TOOL_SURFACE_PROFILEare both set tointentsin the deployedapp.configfile, whatever your previous value. To continue exposing all tools directly, set both tofulland restart the service.TELEMETRY_ENABLEDandTELEMETRY_PUSH_ENABLEDno 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.batfrom 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_URLin the new.envfile 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_HOSTin the new.envfile 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.shandREADME.mdunder<old installer>/backups/pre-mcp-suite-<timestamp>/. This copy exists only for the rollback and is deleted once the update succeeds. - Builds a new
.envfrom 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-servicesandimaging-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_PROFILEandSEMANTIC_MCP_TOOL_SURFACE_PROFILEare both set tointentsin the deployed.envfile, whatever your previousMCP_TOOL_SURFACE_PROFILEvalue. To continue exposing all tools directly, set both tofulland restart the MCP Server with./run.sh --restart.- Any
TELEMETRY_ENABLEDorTELEMETRY_PUSH_ENABLEDvalue 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
- Download and unzip the installation media for the target release.
- 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. 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.
- Download and unzip the installation media for the target release.
- Update the
config/app.configfile to set theSERVICE_HOSTparameter to the IP address, hostname, or FQDN of the machine where MCP Server is installed (the current machine). Important: do not set this aslocalhost. - 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.ymlin the old installation location with the new Docker image. - Remove legacy HTTPS components if present, and the
HTTPS_ENABLEDsetting. - Migrate configuration parameters, preserving your existing settings and adding new ones.
- Update the
run.shscript 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:
- Open the deployed configuration file with a text editor:
%PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config
- Change the required setting(s) and save the file.
- Restart the service with
stop-service.batandstart-service.bat- see Managing the Windows service.
This file holds every setting for the gateway and all three MCP servers. DEBUG_MODE continues to set the verbosity of the structural and semantic search MCP servers, and LOG_LEVEL sets it for the gateway and Text2Cypher. Log file paths come from the service and cannot be changed here.
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:
- Open the deployed configuration file with a text editor:
<installer-root>/.env
- Change the required setting(s) and save the file.
- 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:
- Open the deployed configuration file with a text editor:
%PROGRAMDATA%\CAST\Gatekeeper-MCP-Server\setup-config\app.config
- Change the required setting(s) and save the file.
- 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:
- Open the deployed configuration file with a text editor - to change the listening port, edit
<installer-root>/.envinstead, as its value takes priority:
<installer-root>/config/app.config
- Change the required setting(s) and save the file.
- 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
The uninstall removes the service and deletes both INSTALL_DIR and CONFIG_DIR, including the logs and the Text2Cypher MCP server’s record of ad-hoc queries. Copy anything worth keeping before you run it.
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
The uninstall deletes both the installation folder (%PROGRAMFILES%\Cast\Gatekeeper-MCP-Server) and the configuration folder (%PROGRAMDATA%\CAST\Gatekeeper-MCP-Server), including the logs and any certificates stored there. Back up anything you need first.
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.
- 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
.crtextension. - 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
.pemextension. - 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-----
- 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