MCP Server installation on Microsoft Windows


Overview

This guide covers the installation of CAST Imaging MCP Server 3.1.0-funcrel or later on Microsoft Windows. It’s intended for:

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

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

Architecture

The installer deploys an MCP Aggregator Gateway and the three MCP servers behind it - structural, semantic search and Text2Cypher - as a single Windows service, displayed as CAST Imaging MCP Server, with the service name cast-imaging-mcp-server. Your MCP-aware client always connects to CAST Imaging, which redirects MCP requests to the MCP Aggregator Gateway; the gateway then routes each request to the MCP server able to answer it, presenting the tools of all enabled MCP servers as a single tool surface. See Architecture for how the components fit together.

Starting the service starts the three MCP servers first and then the gateway which fronts them, because the gateway collects their tools as it starts. In the CAST Imaging Control Panel the service registers as MCPSERVER.

The installed layout is as follows:

INSTALL_DIR\
  mcp-gateway\                the gateway, its service scripts, and a folder per MCP server
  tools\
CONFIG_DIR\
  setup-config\app.config     every setting, for the gateway and all three MCP servers
  logs\                       one folder per MCP server, plus the service log

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:

  • the network ports listed in Ports below: 8090 on CAST Imaging for your clients, and 8285 (the MCP Aggregator Gateway, changeable in the configuration.conf file) when MCP Server is installed on its own machine
  • the three MCP servers behind the gateway use ports 8282 (structural), 8287 (semantic search) and 8289 (Text2Cypher) on this machine: your clients never connect to these, so change one only where it clashes with something else on the machine
  • a Neo4j instance reachable from this machine over Bolt - typically the machine where the imaging-viewer component is installed. Semantic search and Text2Cypher both read the CAST Imaging knowledge graph from Neo4j. Disable those MCP servers if Neo4j is not available in your environment - see Choosing which MCP servers run
  • see software requirements for more information about supported Microsoft Windows OS versions
  • a minimum of 2GB free disk space
  • a license key that includes GraphRAG to use the semantic search MCP server - see Semantic search license
  • 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

Ports

Port Listens on Must be reachable from When to open it
8090 The machine hosting the CAST Imaging public gateway (imaging-services) Your MCP-aware clients Always: clients connect to CAST Imaging, never directly to MCP Server. 8090 is the default when CAST Imaging is not configured in HTTPS mode - otherwise, open the port the gateway serves HTTPS on
8285 The MCP Server machine (MCP Aggregator Gateway, set by MCP_GATEWAY_PORT) The machine hosting imaging-services, and the machine hosting imaging-viewer for AI Mode Only when MCP Server is installed on a different machine from imaging-services or imaging-viewer. Clients never connect to it

Semantic search license

Starting from CAST Imaging 3.6.9-funcrel, the semantic search MCP server requires a CAST Imaging license key that includes GraphRAG - see Manage license keys:

  • Contributing Developers strategy: semantic search is available for every application when the global license key includes GraphRAG.
  • Named Application strategy: semantic search is available for an application when that application’s license key includes GraphRAG.

Without it, semantic search is not available and is reported as Not licensed. The structural and Text2Cypher MCP servers are not affected.

CAST Imaging compatibility

MCP Server release Required API version/CAST Imaging release
≥ 3.1.0-funcrel ≥ 3.6.9-funcrel

MCP-aware client connection routing

Your MCP-aware clients connect to CAST Imaging via its public gateway - not direct to the MCP Server. A minimum CAST Imaging release is therefore required as the target installation to ensure proper routing back to the MCP Server - see CAST Imaging compatibility above.

Requests whose route contains /mcp are redirected to the MCP Aggregator Gateway, which then routes each request to the MCP server able to answer it. The MCP Aggregator Gateway registers itself with the CAST Imaging service registry (the Control Panel) under the same name the MCP Server used in earlier releases, so neither CAST Imaging nor your clients need reconfiguring after an update.

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
├── mcpserver_syncronization.bat
└── README.md

mcpserver_syncronization.bat starts the service if it is stopped and confirms that the gateway and every enabled MCP server is healthy - see Step 4 - Run the installation.

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.

The file is read once, at install time, and its values are written to the deployed app.config file which the gateway and all three MCP servers read - see Updating configuration after installation.

HOSTNAME_CONTROL_PANEL=<imaging-services-machine>     # 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=localhost                                # 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=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
PORT_AUTH_SERVICE=                                    # Port of the auth service (AUTH-PROXY), which runs on HOSTNAME_CONTROL_PANEL and fronts the CAST Imaging APIs. Leave empty to read it from the Control Panel registry.
INSTALL_DIR=C:\Program Files\Cast\Imaging-MCP-Server  # Default installation location
CONFIG_DIR=C:\ProgramData\CAST\Imaging-MCP-Server     # Default config setting files location
SSL_CA_BUNDLE=                                        # Sets the path to a self-signed certificate chain exported to file, typically 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).

# Ports
MCP_GATEWAY_PORT=8285                                 # The port CAST Imaging redirects MCP requests to. Clients never connect to it directly, and everything behind it is internal.
MCP_SERVER_PORT=8282                                  # Port the structural MCP server listens on. Clients never connect to this.
MCP_SEMANTIC_PORT=8287                                # Port the semantic search MCP server listens on. Clients never connect to this.
MCP_TEXT_TO_CYPHER_PORT=8289                          # Port the Text2Cypher MCP server listens on. Clients never connect to this.

# Which MCP servers the gateway offers
STRUCTURAL_MCP_ENABLED=true                           # Turn one off where its dependencies are not available - the semantic search and Text2Cypher servers both need Neo4j. See "Choosing which MCP servers run" below.
SEMANTIC_MCP_ENABLED=true
TEXT_TO_CYPHER_MCP_ENABLED=true

# Neo4j - required by the semantic search and Text2Cypher MCP servers
GRAPHRAG_ENABLED=true                                 # Set to true to expose the GraphRAG MCP tools.
NEO4J_URL=bolt://<neo4j-host>:7697                    # Bolt URL of the Neo4j instance holding the CAST Imaging knowledge graph
NEO4J_USER=neo4j                                      # Neo4j user
NEO4J_PASSWORD=<password>                             # Neo4j password

# Tool exposure
STRUCTURAL_MCP_TOOL_SURFACE_PROFILE=intents           # Tool exposure profile for the structural MCP server: "intents" (the default) or "full". Replaces MCP_TOOL_SURFACE_PROFILE.
STRUCTURAL_MCP_INTENTS_HIDDEN_FUNCTIONS=              # Structural capability names to hide when using "STRUCTURAL_MCP_TOOL_SURFACE_PROFILE=intents". Replaces MCP_INTENTS_HIDDEN_FUNCTIONS.
SEMANTIC_MCP_TOOL_SURFACE_PROFILE=intents             # Tool exposure profile for semantic search, using the same values.
SEMANTIC_MCP_INTENTS_HIDDEN_FUNCTIONS=                # Semantic capability names to hide when using "SEMANTIC_MCP_TOOL_SURFACE_PROFILE=intents".
SEMANTIC_MCP_CONVERSATIONAL_MEMORY_ENABLED=false      # When set to true, exposes the conversational memory tools which let an agent persist and search knowledge gathered during a conversation. Requires Neo4j and configured embeddings.

# CAST Imaging query behaviour - applies to the structural and semantic search MCP servers
IMAGING_PAGE_SIZE=1000                                # Sets the number of records the MCP server fetches per request (internal batching).
IMAGING_DISPLAY_PAGE_SIZE=20                          # Sets how many records are shown per page in the user-facing response
IMAGING_CODE=false                                    # Defines whether the application source code is accessible to the MCP Server or not: when it is set to false source code (from the CAST Imaging analysis results) cannot be accessed by the MCP Server and therefore source code will not figure in any results returned by MCP Server
IMAGING_DOMAIN="default"                              # Defines the target domain/tenant to work with. Only valid when IMAGING_DOMAIN_SYNCHRO_ENABLED=true in CAST Imaging.

# Telemetry
TELEMETRY_PUSH_INTERVAL_MINUTES=120                   # Defines how often the telemetry push runs.
TELEMETRY_LOCAL_FILE=                                 # Where telemetry is written. Empty keeps the default, %CONFIG_DIR%\logs\telemetry\telemetry.jsonl, with one folder per tenant beneath it.

# Logging
DEBUG_MODE=false                                      # Sets the log level verbosity of the structural and semantic search MCP servers. Set to true if verbose logs are required.
LOG_LEVEL=INFO                                        # Log level for the gateway and the Text2Cypher MCP server. Supported values are INFO and DEBUG. See the note below.

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. Its underlying service name is cast-imaging-mcp-server.

The installation finishes by health-checking the endpoint: a successful run means the service started, every enabled MCP server came up, and the endpoint answered. To confirm the state of the deployment at any time, run the following from an elevated prompt:

cd /d "%INSTALL_DIR%"
mcpserver_syncronization.bat

This starts the service if it is stopped, waits for the endpoint and every MCP server behind it to report healthy, prints the state of each one, and exits non-zero if any of them never comes up. Pass true to check over HTTPS instead of HTTP.

To check by hand instead:

$ curl http://<SERVICE_HOST>:<MCP_GATEWAY_PORT>/mcpserver/healthcheck
$ curl http://<SERVICE_HOST>:<MCP_GATEWAY_PORT>/mcp/status

/mcp/status returns 200 only when every enabled MCP server is healthy, and names the state of each one, so an MCP server which is down reads differently.

Step 5 - Connect your AI client

Configure each AI client to connect through CAST Imaging, not to the MCP Aggregator Gateway 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. The client configuration is the same as for earlier releases.

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 Update and troubleshoot.

Choosing which MCP servers run

All three MCP servers are installed whichever ones you enable, so you can turn any of them off, or back on, at any time without re-running the installer. A disabled MCP server is not started, and its tools are absent from the gateway. Disable semantic search and Text2Cypher if no Neo4j instance holding the CAST Imaging knowledge graph is available in your environment.

Each MCP server is controlled by one option, which has a different name before and after the installation:

MCP server Before the installation (configuration.conf) After the installation (deployed app.config)
Structural STRUCTURAL_MCP_ENABLED IMAGING_STRUCTURAL_MCP_ENABLED
Semantic search SEMANTIC_MCP_ENABLED IMAGING_SEMANTIC_MCP_ENABLED
Text2Cypher TEXT_TO_CYPHER_MCP_ENABLED IMAGING_TEXT_TO_GRAPH_MCP_ENABLED

All three default to true. Use the name which belongs to the file you are editing: a name taken from the other file is ignored.

Before the installation

Set the option to false in the configuration.conf file, for example TEXT_TO_CYPHER_MCP_ENABLED=false, then run the installation - see Step 4 - Run the installation.

After the installation

Changing configuration.conf after the installation has no effect: an update keeps the values already in the deployed app.config file. Instead:

  1. Open the deployed configuration file with a text editor, from an elevated prompt:

    %PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config
    
  2. Set the option for the MCP server to false to turn it off, or to true to turn it back on, and save the file. For example, to turn off Text2Cypher:

    IMAGING_TEXT_TO_GRAPH_MCP_ENABLED=false
    
  3. Restart the service - see Managing the Windows service:

    cd /d "%INSTALL_DIR%\mcp-gateway"
    stop-service.bat
    start-service.bat
    
  4. Check the result on the MCP Server machine, at http://localhost:<MCP_GATEWAY_PORT>/mcp/servers (8285 by default). It lists each MCP server with whether it is enabled and healthy, and how many tools it exposes - see HTTP endpoints.

Changing a port after the installation

All four ports live in the deployed app.config file, one key per process: MCP_GATEWAY_PORT (the gateway - the port CAST Imaging redirects MCP requests to), MCP_SERVER_PORT (structural), MCP_SEMANTIC_PORT (semantic search) and MCP_TEXT_TO_GRAPH_PORT (Text2Cypher, set from MCP_TEXT_TO_CYPHER_PORT in configuration.conf). Edit one and restart the service: the service rebuilds its routing from the file every time it starts, so the MCP server moves and the gateway follows it.

Managing the Windows service

To restart the deployment - required after any configuration change - run the following from an elevated prompt:

cd /d "%INSTALL_DIR%\mcp-gateway"
stop-service.bat
start-service.bat

Stopping the service stops the three MCP servers with it. Starting it brings them back and the gateway last, since the gateway collects their tools as it starts.

Logs

Everything is under %CONFIG_DIR%\logs\:

mcp_server.log                    the service as Windows sees it, and which MCP servers it waited for
mcp-server-installer.log          the last install, update or uninstall
imaging-mcp-gateway.log           the gateway
imaging-mcp-gateway-activity.log  one JSON line per tool call routed
telemetry\telemetry.jsonl         usage telemetry, one folder per tenant beneath it
imaging-structural-mcp\           mcp_img.log and console.log
imaging-semantic-mcp\             semantic_mcp.log and console.log
imaging-text-to-graph-mcp\        imaging-text2cypher-mcp.log and console.log

Next steps