MCP Server installation on Linux via Docker
Overview
This guide covers the installation of CAST Imaging MCP Server 3.1.0-funcrel or later on Linux via Docker. It’s intended for:
- Direct installation on Linux, via Docker
- 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 Linux via Docker.
The installation package com.castsoftware.imaging.mcpserver.docker includes an installation script and configuration files. All Docker images are pulled direct from Docker Hub during the installation.
Architecture
The installation media delivers one container which runs an MCP Aggregator Gateway and the three MCP servers behind it - structural, semantic search and Text2Cypher. 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.
Only the gateway port is published on the host. The three MCP servers listen on the container’s loopback interface and cannot be reached from outside the container.
Each of the three MCP servers can be turned off individually - 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 and the only port published on the host, changeable in the
.envfile) 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) inside the container: they are not published on the host and require no firewall rule
- a Neo4j instance reachable from this host 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 Linux OS, Docker Engine and Docker Compose
- a minimum of 2GB free disk space
- a license key that includes GraphRAG to use the semantic search MCP server - see Semantic search license
- a functioning release of CAST Imaging (MCP Server interacts with the
imaging-servicescomponent) in your network (see CAST Imaging compatibility below) - an MCP-aware client such as GitHub Copilot (Visual Studio Code)
- authentication for MCP-aware clients can be achieved using 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
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.envfile. This setting is not listed in the file and defaults tofalse(HTTP), which suits most installations. Add it before you run the installation (see Step 3 - Configure your installation), or afterwards and restart (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.
CAST Imaging on Kubernetes
When CAST Imaging is deployed on Kubernetes, the auth service (AUTH-PROXY), which fronts the CAST Imaging APIs, runs as a separate service and not on the Control Panel host. Configure MCP Server as follows:
- Open the
.envfile. - Add a
HOST_AUTH_SERVICEline, which is not present in the file by default, and set it to the hostname of the auth service. Use a hostname that MCP Server can reach. - Optionally, set the existing
PORT_AUTH_SERVICEline to the port of the auth service. When it is left empty, MCP Server reads the port from the Control Panel registry. - Keep
HOST_CONTROL_PANELset to the Control Panel host. - Run the installation (see Step 4 - Run the installation), or restart an existing installation (see Change the configuration after installation).
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 installer using curl:
$ curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.imaging.mcpserver.docker/<version>?platform=linux_x64" -H "x-nuget-apikey: <api-key>" -H "accept: application/octet-stream"
Where:
-#: enables a download progress bar.-O: (--remote-name) ensures the file is downloaded and saved to the current folder using the same name as the remote file.-J: (--remote-header-name) ensures the-Ooption uses the server-specified Content-Disposition filename instead of extracting a filename from the URL. If the server-provided filename contains a path, that is stripped off before the filename is used.<version>: uselatestto download the most recent release, or specify the specific release, e.g.,3.1.0-funcrel.-H: (--header) defines the additional header to include in information sent.<api-key>: your CAST Extend API key (obtain this from your CAST Extend profile settings )
Example for latest release:
$ curl -# -O -J "https://extend.castsoftware.com/api/package/download/com.castsoftware.imaging.mcpserver.docker/latest?platform=linux_x64" -H "x-nuget-apikey: a9999a9a-c999-999d-999b" -H "accept: application/octet-stream"
Unzip the resulting ZIP file anywhere on your local disk. The following files/folders will be created:
com.castsoftware.imaging.mcpserver.docker.<version>/
├── .env # Hidden file (use `ls -a` to view) - all configuration settings
├── docker-compose.yml # Reads the pinned container image from .env
├── mcp_servers.json # Defines where the gateway routes MCP requests
├── run.sh
├── README.md
└── copilot-instructions.md # Optional instructions for GitHub Copilot - see Connect your AI client
run.sh creates three additional folders the first time it runs:
├── certificates/ # Optional CA bundle, mounted read-only
├── data/ # Component data which must survive an update
└── logs/ # One sub-folder per process
./run.sh --update also creates a temporary backups/ folder, which holds the previous configuration until the update succeeds and is then removed.
The config/app.config file delivered by earlier releases is no longer part of the installation media: all settings are in the .env file.
Step 3 - Configure your installation
All settings are held in the .env file at the root of the unzipped installation media. Open the file with a text editor and update the variables to match your environment. Use one KEY=VALUE per line, with no quotes and no inline comments, and leave a value empty to keep the product default.
Three settings are required before you install:
HOST_CONTROL_PANEL=<imaging-services-machine> # Required: IP address/hostname/FQDN of the machine on which the "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 is installed (i.e. the current machine), as your clients and CAST Imaging see it. Do not set as "localhost".
NEO4J_URL= # Required: Bolt URL of the Neo4j instance holding the CAST Imaging knowledge graph, e.g. bolt://<neo4j-host>:7687
The use of localhost for the HOST_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.
The remaining settings are shown below with their default values:
DOCKER_REPO=castimaging # Registry and repository holding the container image. Change only to install from a different registry.
IMAGE_NAME=imaging-mcp-server # Name of the container image.
MCP_IMAGE_TAG=3.1.0 # Set by the installer: image tag. Must be an immutable tag - "latest" is rejected so that an update is always reproducible and reversible.
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 fronts the CAST Imaging APIs. Leave empty to read it from the Control Panel registry. See "CAST Imaging on Kubernetes" above for HOST_AUTH_SERVICE.
MCP_GATEWAY_PORT=8285 # MCP Aggregator Gateway port. This is the only port published on the host, and the port CAST Imaging redirects MCP requests to. Clients never connect to it directly.
MCP_SERVER_PORT=8282 # Structural MCP port inside the container. In previous releases this was the port CAST Imaging redirected to.
MCP_SEMANTIC_PORT=8287 # Semantic search MCP port inside the container.
MCP_TEXT_TO_CYPHER_PORT=8289 # Text2Cypher MCP port inside the container.
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). Place the file in "certificates/" and reference it as /opt/cast/mcp-suite/certificates/<file>.pem
NEO4J_USER=neo4j # Neo4j user
NEO4J_PASSWORD=imaging # Neo4j password
STRUCTURAL_MCP_ENABLED=true # Starts the structural MCP server and exposes its tools through the gateway. See "Choosing which MCP servers run" below.
IMAGING_DOMAIN=default # Defines the target domain/tenant to work with, for the structural and semantic search MCP servers. Only valid when IMAGING_DOMAIN_SYNCHRO_ENABLED=true in CAST Imaging. Text2Cypher takes its domain from the MCP client instead - see the note below.
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 Imaging analysis results) cannot be accessed by the MCP Server and therefore source code will not figure in any results returned by MCP server
STRUCTURAL_MCP_TOOL_SURFACE_PROFILE=intents # Switches the structural MCP server between "meta-tool" mode (intents), where tools are loaded on demand, and classic mode (full), where every tool is exposed directly (requires a restart). See the note below.
STRUCTURAL_MCP_INTENTS_HIDDEN_FUNCTIONS= # Accepts a comma-separated list of structural capability names to hide from the AI aware client when using "STRUCTURAL_MCP_TOOL_SURFACE_PROFILE=intents". See the note below.
SEMANTIC_MCP_ENABLED=true # Starts the semantic search MCP server and exposes its tools through the gateway. Requires Neo4j.
SEMANTIC_MCP_TOOL_SURFACE_PROFILE=intents # Tool exposure profile for semantic search, using the same "intents" and "full" values as the structural setting. See the note below.
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: the vector and full-text indexes are created by the server when the setting is enabled.
TEXT_TO_CYPHER_MCP_ENABLED=true # Starts the Text2Cypher MCP server and exposes its tools through the gateway. Requires Neo4j.
TELEMETRY_LOCAL_FILE=/opt/cast/mcp-suite/logs/telemetry/telemetry.jsonl # Telemetry file inside the container (logs/telemetry/telemetry.jsonl on the host). Other tenants get logs/telemetry/<tenant>/telemetry.jsonl. Keep custom paths below /opt/cast/mcp-suite/logs.
TELEMETRY_PUSH_INTERVAL_MINUTES=120 # Defines how often the telemetry push runs.
LOG_LEVEL=INFO # Sets the log level verbosity for the gateway and all three MCP servers. Supported values are INFO and DEBUG - any other value stops the container at startup. Logs are stored in the "logs/" folder located in the unzipped installation media folder.
- 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. The gateway reads the setting from the Control Panel and checks it again every five minutes.
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.
- No embedding provider settings are configured here. Semantic search reads the embedding provider, model and credentials from the tenant configuration held in Neo4j, which overrides any value supplied through this file. Configure embeddings in CAST Imaging - see AI settings.
- Text2Cypher does not use
IMAGING_DOMAIN. It takes its target CAST Imaging domain (tenant) from thex-user-tenantheader sent by the MCP client, and falls back todefaultwhen the client sends none. It stores its saved queries and activity history in thedata/folder, which survives a restart and an update. LOG_LEVELis the only logging setting in this file. The structural and semantic search MCP servers still read the older booleanDEBUG_MODEinternally, and the container derives it for them:LOG_LEVEL=DEBUGbecomesDEBUG_MODE=true. Do not setDEBUG_MODEhere - it is not read. On Microsoft Windows the two settings are exposed separately, so the equivalent option names differ - see MCP Server installation on Microsoft Windows.
Step 4 - Run the installation
Run the following commands:
$ chmod +x run.sh # makes the installation script executable
$ ./run.sh --install
The installation validates Docker and your configuration, pulls the pinned container image, starts the container, waits until every enabled MCP server reports itself healthy, and prints the resulting endpoint and tool surface. Verify the installation with:
$ ./run.sh --status
The status output lists the container together with each MCP server behind the gateway, its health and its tool count. See Managing your installation for the full list of commands.
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 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 delivered in the container image 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. Disabling all three is allowed: the gateway remains available with an empty tool surface. 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 in the .env file. The same file and option names are used before and after the installation, and an update keeps their values:
| MCP server | Option in .env |
|---|---|
| Structural | STRUCTURAL_MCP_ENABLED |
| Semantic search | SEMANTIC_MCP_ENABLED |
| Text2Cypher | TEXT_TO_CYPHER_MCP_ENABLED |
All three default to true. To change one before the installation, set it in the .env file and run the installation - see Step 4 - Run the installation. After the installation:
-
Open the
.envfile in the installation folder with a text editor:<installer-root>/.env -
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:TEXT_TO_CYPHER_MCP_ENABLED=false -
Apply the change:
$ ./run.sh --restart -
Check the result:
$ ./run.sh --statusEach MCP server is listed with whether it is enabled and healthy, and how many tools it exposes.
The Microsoft Windows installer uses the same option names in its configuration.conf file, but different ones in the deployed app.config file: IMAGING_STRUCTURAL_MCP_ENABLED, IMAGING_SEMANTIC_MCP_ENABLED and IMAGING_TEXT_TO_GRAPH_MCP_ENABLED - see MCP Server installation on Microsoft Windows.
Registering an additional MCP server
The mcp_servers.json file is the address book the gateway uses for routing. Each entry defines where an MCP server is reachable, its health endpoint and its per-request timeout in seconds:
"imaging-semantic-mcp": {
"url": "http://127.0.0.1:8287/mcp",
"timeout": 60,
"health_endpoint": "/health"
}
For the three MCP servers delivered in the container image, the port set in the .env file takes precedence over the port in this file, so change a bundled port in .env - MCP_SERVER_PORT, MCP_SEMANTIC_PORT or MCP_TEXT_TO_CYPHER_PORT - and not here. The remaining values, such as the health endpoint and the timeout, are read from this file.
You can also register an external MCP server here - any MCP server reachable over HTTP. Add an entry with its URL and health endpoint, and its tools join the same tool surface as the bundled ones. Where one of its tools has the same name as a tool already exposed, the gateway prefixes it as <server>:<tool> so that neither is hidden. Only the MCP servers delivered inside the container image can be started by the container: external entries are routed to, not started. To disable an external entry, add its <SERVER_NAME>_ENABLED=false setting to .env, in upper case and with hyphens replaced by underscores.
Changes take effect on ./run.sh --restart.
Managing your installation
| Command | Description |
|---|---|
./run.sh --install |
Fresh installation: validate, pull the image, start, wait for readiness. |
./run.sh --update <path/to/old/installer> |
Update an existing installation to this release. |
./run.sh --start |
Start the container. |
./run.sh --stop |
Stop and remove the container. Logs and data are kept. |
./run.sh --restart |
Apply configuration changes. |
./run.sh --status |
Show the container plus each MCP server with its health and tool count. |
./run.sh --logs |
Follow the container output. |
Logs and data
The logs/ and data/ folders sit in the unzipped installation media folder on the host, so their contents survive a stop, a restart and an update:
logs/
├── gateway/
│ ├── imaging-mcp-gateway.log
│ └── imaging-mcp-gateway-activity.log
├── imaging-structural-mcp/
│ ├── service.log
│ └── telemetry.jsonl
├── imaging-semantic-mcp/
│ └── service.log
└── imaging-text-to-graph-mcp/
└── imaging-text2cypher-mcp.log
data/
└── imaging-text-to-graph-mcp/
├── adhoc_queries.db
└── activity.db
./run.sh --logs follows the combined container output, while the per-process files hold more detail.
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