MCP Server 3.0.x installation on Microsoft Windows
This page covers MCP Server 3.0.x and earlier. Release 3.1.0 delivers an MCP Aggregator Gateway with the structural, semantic search and Text2Cypher MCP servers behind it, and changes the installation and configuration substantially - for 3.1.0 and later, see MCP Server installation on Microsoft Windows.
Overview
This guide covers the installation of CAST Imaging MCP Server 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.imaging.mcpserver includes an installation script (.bat file), various configuration files and the binaries themselves.
Requirements
MCP Server 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 Microsoft Windows service on TCP port 8282 although you can change this in the
configuration.conffile (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 Microsoft Windows OS versions
- a minimum of 2GB free disk space
- an MCP-aware client such as GitHub Copilot (Visual Studio Code)
- a functioning release of CAST Imaging (MCP Server interacts with the
imaging-servicescomponent) in your network (see CAST Imaging compatibility below) - a CAST Imaging API key, see Generating an API key. Available in ≥ 3.6.6-funcrelAlternatively, Claude Code and Visual Studio Code can sign in through the browser using OAuth - see Authenticate MCP clients with OAuth
CAST Imaging compatibility
| MCP Server release | Required API version/CAST Imaging release |
|---|---|
| 3.0.1-funcrel, 3.0.2-funcrel, 3.0.3-funcrel, 3.0.4-funcrel | ≥ 3.6.0-funcrel |
| 3.0.0-funcrel | ≥ 3.5.9-funcrel |
| 1.3.0-funcrel | ≥ 3.5.5-funcrel |
| 1.2.0-funcrel | ≥ 3.5.3-funcrel |
| ≤ 1.1.x | ≥ 3.4.0-funcrel. For best results, CAST highly recommends ≥ 3.4.5-funcrel. |
- For MCP Server 3.1.0 and later, see MCP Server installation on Microsoft Windows or MCP Server installation on Linux via Docker.
- Starting release 3.0.1-funcrel, it is possible to check the current CAST MCP Server version, the connected CAST Imaging API version, and the recommended CAST Imaging API version for the CAST MCP server in use by asking “What is the version of my MCP server and Imaging APIs? Are these services compatible?”
MCP-aware client connection routing
Starting release 1.2.0-funcrel, MCP-aware clients must now connect directly to CAST Imaging via its public gateway - instead of direct to the MCP Server. As a result, CAST Imaging 3.5.3-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.
- If the CAST Imaging gateway is configured in HTTPS mode, then the
CONTROL_PANEL_SSL_ENABLEDoption must be set to true in the MCP Server itself (see Step 3 - Configure your installation). - If the CAST Imaging gateway is configured in HTTPS mode with self-signed or private certificate authority SSL/TLS certificates, then you will need to ALSO define the path to the certificate chain with
SSL_CA_BUNDLE. See below.
Recommended LLMs
Not all models perform equally for tool invocation, reasoning and response reliability - see Recommended LLMs.
What’s new?
See the release notes.
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/rest/ready
The expected output is true.
Step 2 - Download the installation media
Download the latest release of the installer (com.castsoftware.imaging.mcpserver ) and unzip it anywhere on your local disk. The following files/folders will be created:
com.castsoftware.imaging.mcpserver.<version>/
├── 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 following settings to match your environment - the other settings can be left at their defaults:
HOSTNAME_CONTROL_PANEL=<imaging-services-machine>
SERVICE_HOST=<mcp-server-machine>
PORT_CONTROL_PANEL=8098
INSTALL_DIR=C:\Program Files\Cast\Imaging-MCP-Server
CONFIG_DIR=C:\ProgramData\CAST\Imaging-MCP-Server
MCP_SERVER_PORT=8282
DEBUG_MODE=false
IMAGING_PAGE_SIZE=1000
IMAGING_DISPLAY_PAGE_SIZE=20
IMAGING_CODE=False
IMAGING_DOMAIN=default
CONTROL_PANEL_SSL_ENABLED=false
MCP_TOOL_SURFACE_PROFILE=full
MCP_INTENTS_HIDDEN_FUNCTIONS=
SSL_CA_BUNDLE=
Do not add comments at the end of a line: the installer reads everything after the = sign as the value, so a trailing comment corrupts the setting. Place comments on their own line, starting with #.
| Setting | Description |
|---|---|
HOSTNAME_CONTROL_PANEL |
Required: IP address/hostname/FQDN of the machine on which the CAST Imaging imaging-services component is installed. The use of localhost is not supported. |
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 leave this set as localhost. |
PORT_CONTROL_PANEL |
Port on which the CAST Imaging Control Panel service (part of the imaging-services component) is running - unless you have changed it during the CAST Imaging installation, leave it as is. |
INSTALL_DIR |
Installation location. |
CONFIG_DIR |
Location of the configuration files and logs. |
MCP_SERVER_PORT |
MCP Server listening port, 8282 by default. |
DEBUG_MODE |
Set to true for verbose logs. Logs are stored in <INSTALL_DIR>\logs\mcp_server.log. |
IMAGING_PAGE_SIZE |
Number of records the MCP Server fetches per request (internal batching). |
IMAGING_DISPLAY_PAGE_SIZE |
Number of records shown per page in the user-facing response. |
IMAGING_CODE |
Defines whether the application source code is accessible to the MCP Server. When set to False, source code (from the CAST Imaging analysis results) cannot be accessed by the MCP Server and does not figure in any results it returns. |
IMAGING_DOMAIN |
Target domain (tenant). Only valid for CAST Imaging 3.5.0-funcrel or later, when IMAGING_DOMAIN_SYNCHRO_ENABLED=true. |
CONTROL_PANEL_SSL_ENABLED |
Set to true to communicate with a CAST Imaging instance configured to use HTTPS. |
MCP_TOOL_SURFACE_PROFILE |
full (default): every tool is exposed directly. intents: meta-tool mode, where tools are loaded on demand. Only valid for MCP Server 3.0.2-funcrel or later. No other value is accepted. |
MCP_INTENTS_HIDDEN_FUNCTIONS |
Comma-separated list of capability names to hide from the AI client when MCP_TOOL_SURFACE_PROFILE=intents. |
SSL_CA_BUNDLE |
Path to a certificate chain 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) - see HTTPS with self-signed or private CA certificates. It can be set here or after the installation. |
The use of localhost for the HOSTNAME_CONTROL_PANEL variable is not supported, even if the imaging-services component is installed on the same machine as MCP Server. Use an IP address/hostname/FQDN instead.
See Meta Tool mode for more information about the MCP_TOOL_SURFACE_PROFILE and MCP_INTENTS_HIDDEN_FUNCTIONS options.
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
On completion, check that a Microsoft Windows service named CAST Imaging MCP Server has been created and is up and running.
If you want to check that the MCP Server is up and running, you should leverage MCP Inspector to do so (this is beyond the scope of this documentation). Direct calls to the MCP Server URL from a browser will result in a .json return stating “Not Acceptable: Client must accept text/event-stream”.
Step 5 - Connect your AI client
Configure each AI client to connect through CAST Imaging, not to the MCP Server directly - see Connect your AI client. It covers GitHub Copilot, Claude Code, Cursor, OpenAI Codex, Gemini CLI and Claude Desktop, with API key or OAuth sign-in.
Step 6 - Test the connection
From an AI client, ask List all applications. If you get an answer, the MCP Server is working. Otherwise, see Test your connection and the Troubleshooting section below.
Example queries
See CAST Imaging MCP for example prompts.
Available Toolsets
See the Tools reference.
Troubleshooting
- Check the Microsoft Windows service CAST Imaging MCP Server (service name
cast-imaging-mcp-server) and restart it if required. - Check the MCP Server logs in the
logsfolder of the installation, by default:
C:\Program Files\Cast\Imaging-MCP-Server\logs\mcp_server.log
C:\Program Files\Cast\Imaging-MCP-Server\logs\mcp-server-installer.log
- Test connectivity to CAST Imaging API:
$ curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/rest/ready
-
Validate configuration files:
- Check
%PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config - Ensure
"url"parameter in the clientmcp.jsonpoints to correct URL
- Check
-
Regenerate API key in CAST Imaging profile if necessary.
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:
Creating the PEM file
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.
Combine into a single PEM file
If you have both a root and intermediate certificate, combine them into a single PEM file. If you only have a root certificate, simply rename it with a .pem extension.
CMD:
copy /b root.crt + intermediate.crt my_cert.pem
PowerShell:
Get-Content root.crt, intermediate.crt | Set-Content my_cert.pem
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
Create a certificates folder in the configuration folder of the MCP Server and place the PEM file inside it:
%PROGRAMDATA%\CAST\Imaging-MCP-Server\certificates\my_cert.pem
Configure and restart MCP Server
Open %PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config and set the existing SSL_CA_BUNDLE line to the path of the .pem file created earlier:
SSL_CA_BUNDLE=C:\ProgramData\CAST\Imaging-MCP-Server\certificates\my_cert.pem
Restart the MCP Server using the Windows Service manager to ensure the setting is taken into account. The certificate can also be set before the installation, with SSL_CA_BUNDLE in configuration.conf.
Updating configuration after installation
To change a configuration option (for example IMAGING_CODE, DEBUG_MODE, or CONTROL_PANEL_SSL_ENABLED) 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 CAST Imaging MCP Server Windows service (using the Windows Service manager) for the change to be taken into account.
Update process
Before updating, check that your CAST Imaging release supports the target MCP Server release - see CAST Imaging compatibility.
The installation media includes a dedicated update option that performs an in-place update to a new release of CAST MCP Server. The update reads the existing installation from the Windows registry: no changes to configuration.conf are needed.
- Download and unzip the installation media for the target release.
- 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
- After the update, open
%PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.configand check thatSERVICE_HOSTis set to the IP address, hostname or FQDN of the current machine. If the update had to add the setting, it uses the IP address of the machine, orlocalhostif that cannot be determined - do not leave it set aslocalhost. Restart the CAST Imaging MCP Server Windows service if you change it.
What does the update do?
- Stops the CAST Imaging MCP Server Windows service.
- Migrates the existing
app.config: renamesEUREKA_HOSTandEUREKA_PORTtoHOST_CONTROL_PANELandPORT_CONTROL_PANEL, removesHTTPS_ENABLEDandMCP_NGINX_PORT, and adds any missing setting with its default value, preserving your existing settings. - Replaces the MCP Server executable.
- Removes the legacy
cast-imaging-mcp-nginxservice and its files if present. - Restarts the service and checks its health.
Post-update action items
After updating from a release earlier than 1.2.0-funcrel
You must reconfigure all MCP-aware clients to point to the CAST Imaging imaging-services machine instead of directly to the MCP Server - see Connect your AI client.
Uninstall process
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 deletes both the installation folder (%PROGRAMFILES%\Cast\Imaging-MCP-Server) and the configuration folder (%PROGRAMDATA%\CAST\Imaging-MCP-Server), including the logs and any certificates stored there. Back up anything you need first.