MCP Server 3.0.x installation on Linux via Docker
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 Linux via Docker.
Overview
This guide covers the installation of CAST Imaging MCP Server on Linux via Docker. It’s intended for:
- Direct installation on Linux, via Docker
- new installations (i.e. from scratch)
- in-place updates to a new release
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.
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 Docker container on TCP port 8282 although you can change this in the
.envfile (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 Linux OS, Docker Engine and Docker Compose
- a minimum of 2GB free disk space
- 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
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 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.,1.0.1-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>/
├── config/
│ └── app.config
├── .env # Hidden file (use `ls -a` to view)
├── copilot-instructions.md
├── docker-compose.yml
├── README.md
└── run.sh
Step 3 - Configure your installation
app.config
Locate the config/app.config 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:
HOST_CONTROL_PANEL="<imaging-services-machine>"
PORT_CONTROL_PANEL=8098
IMAGING_PAGE_SIZE=1000
IMAGING_DISPLAY_PAGE_SIZE=20
IMAGING_CODE=False
DEBUG_MODE=false
IMAGING_DOMAIN="default"
CONTROL_PANEL_SSL_ENABLED=false
MCP_TOOL_SURFACE_PROFILE="full"
MCP_INTENTS_HIDDEN_FUNCTIONS=""
SERVICE_HOST="<mcp-server-machine>"
SSL_CA_BUNDLE=""
The installation script reads this file as a shell script: do not add comments at the end of a line, and keep values that contain spaces or special characters within quotes.
| Setting | Description |
|---|---|
HOST_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. |
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. |
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. |
DEBUG_MODE |
Set to true for verbose logs. Logs are stored in logs/mcp_img.log at the root of the installer. |
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". |
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 set as localhost. |
SSL_CA_BUNDLE |
In-container path to a certificate chain in Base-64 PEM format, for example /app/certificates/my_cert.pem: place the file in the certificates/ folder at the root of the installer, which is mounted read-only at /app/certificates. Only necessary where CAST Imaging is configured in HTTPS mode with certificates issued by a private or self-signed CA - see HTTPS with self-signed or private CA certificates. |
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.
See Meta Tool mode for more information about the MCP_TOOL_SURFACE_PROFILE and MCP_INTENTS_HIDDEN_FUNCTIONS options.
.env
Locate the .env file at the root of the unzipped installation media. Open the file with a text editor and set the MCP server listening port (the default is set to 8282):
MCP_SERVER_PORT=8282
Step 4 - Run the installation
Run the following commands:
$ chmod +x run.sh # makes the installation script executable
$ ./run.sh --install
Verify the installation by checking Docker containers (you should see one Docker container hosting the MCP Server):
$ docker ps
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 MCP Server container, named
mcp-server, is running:
$ docker ps | grep imaging-mcp
- Check the MCP Server logs:
$ docker logs mcp-server
or the logs/mcp_img.log file at the root of the installer folder.
- 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
config/app.config - Check
.envfile for correct port configuration - 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.
$ cat root.crt intermediate.crt > 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
Place the PEM file inside the certificates folder at the root of the installer (the same directory as run.sh). The folder is created automatically by run.sh and mounted read-only in the container at /app/certificates; if it is missing, create it manually:
<installer-root>/certificates/my_cert.pem
Configure and restart MCP Server
Open <installer-root>/config/app.config and set the existing SSL_CA_BUNDLE line using the in-container path:
SSL_CA_BUNDLE=/app/certificates/my_cert.pem
Restart the MCP Server to ensure the setting is taken into account:
$ docker compose down
$ ./run.sh
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 - to change the listening port, edit
<installer-root>/.envinstead:
<installer-root>/config/app.config
- Change the required setting(s) and save the file.
- Restart the MCP Server container for the change to be taken into account:
$ docker compose down
$ ./run.sh
Update process
Before updating, check that your CAST Imaging release supports the target MCP Server release - see CAST Imaging compatibility.
Starting 1.2.0-funcrel, the installation media includes a dedicated update option that performs an in-place update to a new release of CAST MCP Server:
- Download and unzip the installation media for the target release.
- If you are updating from a release earlier than 1.2.0-funcrel, set
SERVICE_HOSTin theconfig/app.configfile of the new installer to the IP address, hostname or FQDN of the current machine - do not set it aslocalhost. For later releases,SERVICE_HOSTis already present in the existing installation and is kept: to change it, edit theconfig/app.configfile of the existing installation instead. - Run the following commands from the new installer folder:
$ chmod +x run.sh # makes the installation script executable
$ ./run.sh --update /path/to/old/installer # updates the existing installation
What does the update do?
This process preserves your existing configuration and data while updating the Docker image and scripts, i.e. the following will occur:
- Stop the existing containers from the old installation location.
- Update the
docker-compose.ymlin the old installation location with the new Docker image. - Migrate configuration parameters, preserving your existing settings and adding new ones that are missing.
- Remove legacy HTTPS components if present: the
mcp-nginx-proxycontainer,docker-compose.https.ymland thenginx/folder. - Update the
run.shscript in the old installation location and create itscertificates/folder. - Restart the MCP Server from the old installation location.
The installation remains in the old installer folder, with its existing .env file: make all later configuration changes there. The new installer folder can be deleted once the update has completed.
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
There is no uninstall option for Linux via Docker. To remove the MCP Server, stop and remove its container, then remove its image:
$ cd /<installer-root>
$ docker compose down
$ docker images | grep imaging-mcp-server
$ docker rmi <image-id> # only if you are sure
Then delete the installer folder and the installer ZIP file.