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 https://hub.docker.com 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 and outgoing 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
CAST Imaging ≥ 3.4.1 installed and functioning (MCP Server interacts with the imaging-services component) in your network
a MCP-aware client such as GitHub Copilot (Visual Studio Code), Claude Desktop etc.
a CAST Imaging API key, see Generating an API key

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/#/extension?id=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 https://extend.castsoftware.com/#/profile/settings )

Example for latest release:

curl -# -O -J "https://extend.castsoftware.com/#/extension?id=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:

imaging-mcp-server-installer/
├── config/
│   └── app.config
├── nginx/
│   └── nginx.conf
├── .env                        # Hidden file (use `ls -a` to view)
├── docker-compose.yml
├── docker-compose.https.yml
├── run.sh
├── README.md
├── MCP-copilot-setup.md
└── copilot-instructions.md

Step 3 - Configure your installation

app.config

Locate the config/app.config file in the unzipped files. Open the file with a text editor and update the installation variables to match your environment:

HOSTNAME_CONTROL_PANEL="imaging-services machine"      # Required: IP address/hostname/FQDN of the machine on which the "imaging-services" component is installed. You can use localhost if MCP Server is installed on the same machine as the "imaging-services" component.
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
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
HTTPS_ENABLED=false                                   # Enable HTTPS between MCP-aware client and MCP Server (requires appropriate certificates)

.env

Locate the .env file at the root of the unzipped files. Open the file with a text editor and set the MCP server listening port. If you are to have the server running on port 8282 you do not need to make any changes:

MCP_SERVER_PORT=8282    # Default port

Optional: establishing a HTTPS connection between the MCP-aware client and the MCP Server

If you need to establish a secure HTTPS connection between the MCP-aware client and MCP server, follow these steps:

Locate the config/app.config file in the unzipped files. Open the file with a text editor and update the HTTPS_ENABLED variable to true:

HTTPS_ENABLED=true

Create a folder named certificates in the root of the imaging-mcp-server-installer folder. Inside this folder, add your certificate and private key files with the following names:

certificate.pem – the secure certificate
private_key.pem – the corresponding private key

Creating the key file pair is beyond the scope of this documentation.
The MCP Server will be automatically set to listen on port 8443.

Step 4 - Run the installation

Run the following commands:

chmod +x run.sh    # makes the installation script executable
./run.sh

Verify the installation by checking Docker containers (you should see one Docker container hosting the MCP Server):

docker ps

Step 5 - Configure an MCP-Aware client

Create a mcp.json configuration file for your MCP-aware client. The storage location for this file depends on your client:

GitHub Copilot (Visual Studio Code): .vscode/mcp.json in your workspace
Claude Desktop: Client-specific configuration directory

The mcp.json must use the following template:

{
  "inputs": [
    {
      "id": "imaging-key",
      "type": "promptString",
      "description": "Imaging API Key"
    }
  ],
  "servers": {
    "imaging": {
      "type": "http",
      "url": "http://<your-mcp-server-host:port>/mcp/",
      "headers": {
        "imaging_api_key": "${input:imaging-key}"
      }
    }
  }
}

where:

"type" is set to http or https depending on whether the MCP Server is set to run in secure HTTPS mode or not
"url" is the IP address/hostname/FQDN and port number (8282 by default) of the machine hosting the MCP Server. Ensure you use either http or https depending on whether the MCP Server is set to run in secure HTTPS mode or not

Step 6 - Test your MCP-Aware client

Launch your MCP-aware client
Enter your CAST Imaging API key when prompted
Run a test query, for example:

List all applications

or:

List 5 transactions for application <your-application-name>

If successful (see below), you’re ready to use your MCP Client with your MCP Server.

Success indicators

✅ Connection successful if you receive:

Valid application listings
Architectural insights
Suggested analysis queries

❌ Check configuration if you see:

Connection errors
Authentication failures
Empty responses

Example queries

Basic application information

List all applications

Transaction analysis

List all applications transactions
Show 10 transactions for application MyApp

Data flow analysis

List available applications datagraphs
Show data graphs for application MyApp

Quality insights

List applications insights
Show quality issues for application MyApp

Architectural analysis

Analyze the architecture of MyApp
Show dependencies for MyApp

Troubleshooting

Check the MCP Server container is running:

docker ps | grep imaging-mcp

Check MCP Server logs:

docker logs <container-id>

Test connectivity to CAST Imaging API:

curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/rest/ready

curl -H "x-api-key: <your-imaging-api-key>" https://<your_imaging_public_URL>:8443/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.

Update process

???

Uninstall process

To remove only MCP Server related items:

run the following Docker commands
delete the installer ZIP file
delete the unzipped installation files/folder

# Stop imaging-services containers
cd /<unzipped-install-files>
docker compose down

# Remove images
docker images | grep $servicename | awk '{print $3}' | xargs -I {} docker rmi -f {}
docker image prune