MCP Server 3.0.x 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 external link includes an installation script and configuration files. All Docker images are pulled direct from Docker Hub external link 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 .env 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 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-services component) 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-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 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 -O option 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>: use latest to 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 external link)

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=""

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.

.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

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 .env file for correct port configuration
    • 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.

$ 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:

  1. Open the deployed configuration file with a text editor - to change the listening port, edit <installer-root>/.env instead:
<installer-root>/config/app.config
  1. Change the required setting(s) and save the file.
  2. 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:

  1. Download and unzip the installation media for the target release.
  2. If you are updating from a release earlier than 1.2.0-funcrel, set SERVICE_HOST in the config/app.config file of the new installer to the IP address, hostname or FQDN of the current machine - do not set it as localhost. For later releases, SERVICE_HOST is already present in the existing installation and is kept: to change it, edit the config/app.config file of the existing installation instead.
  3. 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.yml in 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-proxy container, docker-compose.https.yml and the nginx/ folder.
  • Update the run.sh script in the old installation location and create its certificates/ 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.

FAQ

See Frequently Asked Questions.