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
For MCP Server 3.0.x and earlier, see MCP Server 3.0.x installation on Microsoft Windows.
The installation package com.castsoftware.imaging.mcpserver 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
All three MCP servers are installed whether or not they are enabled, so you can turn one on or off later without re-running the installer - see Choosing which MCP servers run.
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.conffile) 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-viewercomponent 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-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
The installation stops if a port you name in configuration.conf is already in use on the machine. Leave a port empty to keep the default shown.
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 |
The MCP Aggregator Gateway does not check the API key - CAST Imaging checks it before forwarding a request. Allow access to port 8285 only from the machines hosting imaging-services and imaging-viewer, and block it from every other machine, even when MCP Server runs on the same machine as CAST Imaging. On Linux via Docker, the port is published on all network interfaces and Docker’s own rules bypass host firewalls such as ufw or firewalld: add the restriction to the DOCKER-USER chain or to a network firewall.
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 Developersstrategy: semantic search is available for every application when the global license key includes GraphRAG.Named Applicationstrategy: 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 |
- It is possible to check the current CAST MCP Server release, 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?”
- For MCP Server 3.0.x and earlier, see MCP Server 3.0.x installation on Linux via Docker or MCP Server 3.0.x installation on Microsoft Windows.
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.
- If the CAST Imaging Control Panel is served over HTTPS, add
CONTROL_PANEL_SSL_ENABLED=trueto the configuration file. This setting is not listed in the file and defaults tofalse(HTTP), which suits most installations. Add it toconfiguration.confbefore you run the installation (see Step 3 - Configure your installation), or to the deployedapp.configfile afterwards (see Updating configuration after installation). - If the CAST Imaging gateway is configured in HTTPS mode with self-signed or private certificate authority SSL/TLS certificates, you will also need to define the path to the self-signed certificate chain once the installation has completed. 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
├── 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.
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.
- Telemetry has no on/off setting in this file. For each tenant, the CAST Imaging setting Allow CAST to automatically collect anonymous statistical data decides whether telemetry is recorded and pushed to CAST.
TELEMETRY_ENABLEDandTELEMETRY_PUSH_ENABLEDare still present in the deliveredconfiguration.conffile but are not used. IMAGING_CODE=trueallows the MCP Server to return application source code (from the CAST Imaging analysis results) in its responses, so that it is sent to the LLM used by your MCP-aware client.- See Meta Tool mode for more information about the tool surface profile and hidden function settings.
- The semantic search MCP server’s AI/embedding provider keys and GraphRAG index names keep sensible defaults and do not need to be set here. Configure embeddings in CAST Imaging - see AI settings.
- Logging uses two separate settings on Microsoft Windows:
LOG_LEVEL(INFOorDEBUG) for the gateway and Text2Cypher, and the older booleanDEBUG_MODEfor the structural and semantic search MCP servers. Set both to raise verbosity across the whole deployment. The Docker installer exposesLOG_LEVELalone and derivesDEBUG_MODEfrom it, so the option names differ between the two installers even though the underlying components are the same - see MCP Server installation on Linux via Docker. - Log file paths come from the Windows service rather than from
configuration.conf, and are not configurable - see Logs.
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.
- Microsoft Windows does not always bring a service back after a reboot. Consider scheduling
mcpserver_syncronization.batas an elevated Windows task at startup. - 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
.jsonreturn 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 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:
-
Open the deployed configuration file with a text editor, from an elevated prompt:
%PROGRAMDATA%\CAST\Imaging-MCP-Server\setup-config\app.config -
Set the option for the MCP server to
falseto turn it off, or totrueto turn it back on, and save the file. For example, to turn off Text2Cypher:IMAGING_TEXT_TO_GRAPH_MCP_ENABLED=false -
Restart the service - see Managing the Windows service:
cd /d "%INSTALL_DIR%\mcp-gateway" stop-service.bat start-service.bat -
Check the result on the MCP Server machine, at
http://localhost:<MCP_GATEWAY_PORT>/mcp/servers(8285by default). It lists each MCP server with whether it is enabled and healthy, and how many tools it exposes - see HTTP endpoints.
The Docker installer uses the configuration.conf names, STRUCTURAL_MCP_ENABLED, SEMANTIC_MCP_ENABLED and TEXT_TO_CYPHER_MCP_ENABLED, in its .env file - see MCP Server installation on Linux via Docker.
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.
Nothing checks that the port you pick is free when you edit app.config directly. A port already held by something else leaves that MCP server failing to bind: it will be missing from /mcp/status, with the reason in its own log. To have the installer check the ports first, edit configuration.conf instead and pass it to an update - mcp-server-installer.bat --update configuration.conf.
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
- Connect your AI client - client configuration for your developers
- Update and troubleshoot - update, reconfigure, uninstall and troubleshoot the MCP Server
- Frequently Asked Questions