MCP Server 3.0.x 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 external link 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.conf 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 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-services component) in your network (see CAST Imaging compatibility below)
  • a CAST Imaging API key, see Generating an API key.
    Available in ≥ 3.6.6-funcrel
    Alternatively, 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.

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.

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 external link) 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=

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.

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.

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 logs folder 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 client mcp.json points to correct URL
  • 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:

  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 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.

  1. Download and unzip the installation media for the target release.
  2. Open a CMD window with elevated permissions (right click, Run as administrator).
  3. Navigate to the root directory of the unzipped files and run:
mcp-server-installer.bat --update
  1. After the update, open %PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config and check that SERVICE_HOST is 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, or localhost if that cannot be determined - do not leave it set as localhost. 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: renames EUREKA_HOST and EUREKA_PORT to HOST_CONTROL_PANEL and PORT_CONTROL_PANEL, removes HTTPS_ENABLED and MCP_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-nginx service 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

FAQ

See Frequently Asked Questions.