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 external link includes an installation script and configuration files. All Docker images are pulled direct from https://hub.docker.com 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 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.0 installed and functioning (MCP Server interacts with the imaging-services component) in your network (* see note 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

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 external link)

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:

com.castsoftware.imaging.mcpserver.docker.<version>/
├── config/
│   └── app.config
├── nginx/
│   └── nginx.conf
├── .env                        # Hidden file (use `ls -a` to view)
├── copilot-instructions.md
├── docker-compose.https.yml
├── 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 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
DEBUG_MODE=false                                      # Sets the log level verbosity. Set to true if verbose logs are required. Logs are stored in the "logs/" folder located in the unzipped installation media folder
HTTPS_ENABLED=false                                   # Enable HTTPS between MCP-aware client and MCP Server (requires appropriate certificates). Forces the use of the docker-compose.https.yml file instead of docker-compose.yml
IMAGING_DOMAIN="default"                              # Defines the target domain/tenant to work with. Only valid for CAST Imaging  3.5.0-funcrel or later, when IMAGING_DOMAIN_SYNCHRO_ENABLED=true.
CONTROL_PANEL_SSL_ENABLED=false                       # When set to true, allows communication with a CAST Imaging instance which is configured to use HTTPS.

.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    # 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:

  1. Locate the config/app.config file at the root of the unzipped installation media. Open the file with a text editor and update the HTTPS_ENABLED variable to true:
HTTPS_ENABLED=true
  1. Create a folder named certificates in the root of the unzipped installation media 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

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 your MCP-Aware client (GitHub Copilot for Visual Studio Code)

Install GitHub Copilot extension

Install the GitHub Copilot extension (see https://marketplace.visualstudio.com/items?itemName=GitHub.copilot external link) in Visual Studio Code, ensure you are signed in to GitHub and clone the repository you need to work with.

Create mcp.json file

Create an mcp.json configuration file and place it in the .vscode/ folder for your Visual Studio Code workspace. The mcp.json must use the following template:

{
  "inputs": [
    {
      "id": "imaging-key",
      "type": "promptString",
      "description": "CAST Imaging API Key"
    }
  ],
  "servers": {
    "imaging": {
      "type": "http",
      "url": "http://<your-mcp-server-host:port>/mcp/",
      "headers": {
        "x-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.

Manage copilot-instructions.md file

Locate the copilot-instructions.md file at the root of the unzipped installation media and copy it into a folder called .github located at the root of the repository you are working with. This file provides provide chat responses that are tailored to CAST Imaging: the additional information is not displayed in the chat, but is available to Copilot to allow it to generate higher quality responses.

Alternative manual registration flow

If Visual Studio Code does not auto‑pick the MCP server:

  1. Open Copilot Chat → gear icon → Select tools that are available to chat
  2. + Add More Tools… → + Add MCP Server… → choose HTTP
  3. Enter http(s)://<your-mcp-server-host:port>/mcp/ and confirm
  4. Visual Studio Code will then create .vscode/copilot/mcp.json → add the header block:
"my-mcp-server-xxxx": {
  "url": "http://<your-mcp-server-host:port>/mcp/",
  "headers": {
    "x-api-key": "${input:imaging-key}"
  }
}

Step 6 - Test your MCP-Aware client

  1. Launch your MCP-aware client
  2. Enter your CAST Imaging API key when prompted
  3. Run a test query, for example:
List all applications
List 5 transactions for application <YourApp>
List available applications datagraphs
List applications insights

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

Use the following example queries for the fictional application “Shopizer” as inspiration for your own queries:

Basic application information

Show me all applications available in my Imaging environment.
Which application has the largest number of transactions?

Transaction analysis

Explain about the entire graph of #customer-create-link transaction present in the Shopizer App.

List all the transactions in Shopizer app with the name containing “customer”.

Add a post-it on the transaction named #customer-create-link in Shopizer with title as "MCP post-it" and description as "This is a post-it created by MCP server".

Data flow analysis

Explain about the entire graph of CATEGORIES_DESCRIPTION datagraph present in the Shopizer App.

List all the data call graphs in Shopizer app with the name containing "CATEGORIES".

Add a post-it on the data graph named CENTRAL_CREDIT_CARDS in Shopizer with title as "MCP post-it" and description as "This is a post-it created by MCP server".

Quality insights

List all the ISO-5055 quality insights in the object pageProductReviews in Shopizer app?

List the top 5 structural flaws by occurrence count in app Shopizer.

List some of the green deficiencies present in the app Shopizer app.

Architectural analysis

Provide the high-level architecture view of Shopizer app.

Explain the architecture Shopizer app at  User Interaction Level.

Available Toolsets

  • Portfolio tools - tools for overall portfolio exploration for cross-application analysis when users want to explore multiple applications, compare metrics across the entire portfolio, or discover available applications before diving into specific ones.
  • Application tools - tools for application-level exploration for analyzing a single application in depth, covering architecture, quality insights, transactions, data graphs, packages, dependencies, and overall application statistics and structure.
  • Object tools - Object level exploration for drilling down into specific code artifacts (classes, methods, tables, functions) within an application - examining their properties, relationships, callers/callees, usage in transactions, and associated quality insights. This includes the following tools:

Portfolio tools

  • applications - list all available applications available in CAST Imaging.
  • applications_transactions - retrieve transactions across all applications available in CAST Imaging with optional filtering.
  • applications_data_graphs - retrieve Data Call Graph views across all applications available in CAST Imaging with filtering.
  • applications_dependencies - analyse inter-application dependencies across the applications available showing incoming and outgoing relationships for each app.
  • applications_quality_insights - get quality insights across all applications in CAST Imaging with selective insight types:
    • cve - security vulnerabilities
    • cloud - cloud maturity patterns
    • green - sustainability patterns
    • structural-flaws - architectural issues
    • iso-5055 - ISO quality violations
  • inter_applications_dependencies - analyze dependencies between applications showing inward (apps depending on this) and outward (apps this depends on) relationships.
  • inter_app_detailed_dependencies - get detailed dependency information between two specific applications showing exact interaction points.

Application tools

  • stats - get basic statistics for an application including size, complexity, and technology metrics.
  • architectural_graph - visualize application architecture (nodes/links) for an application at a specific abstraction levels (layer, component, sub-component, technology-category, element-type).
  • architectural_graph_focus - get architecture focused on specific components for an application, useful for exploring architecture around key areas.
  • quality_insights - retrieve quality issues and vulnerabilities including CVE, cloud patterns, green patterns, structural flaws, and ISO-5055 violations for an application.
  • quality_insight_violations - get detailed information about the occurrences (specific locations) for a particular quality related insight type and ID in an application. Returns quality patterns and violating objects and their details.
  • packages - list external packages, libraries or dependencies used by the application.
  • package_interactions - analyze interactions between different packages for an application to understand dependency relationships with it.
  • transactions - fetch transactions for an application with optional filtering capabilities by name or type of the transaction.
  • transaction_details - get comprehensive details about specific transactions with multiple focus options:
    • complexity - list of complex objects in the flow graph of transaction.
    • insights - list objects in the transaction flow with Quality insights
    • nodes - list of all objects in the transaction graph
    • links - list of all links/connections between objects in the transaction graph
    • graph - full call graph of the transaction
    • type_graph - graph results aggregated by object types
    • complexity_graph - reduced version of a transaction graph to represent only most complex objects.
    • documents - list documents like post-its attached to a transaction
    • summary - fetch the AI-generated summary attached to the transaction (if available)
  • add_view_document - add document (i.e. post-its) to transactions or data graphs for knowledge capture.
  • data_graphs - fetch data call graph views for an application with optional filtering capabilities.
  • data_graph_details - get detailed information about specific data call graph flow with multiple focus options:
    • complexity - list of complex objects in the flow graph of a data call graph.
    • insights - list objects in the data call graph flow with Quality insights
    • nodes - list of all objects in the data call graph.
    • links - list of all links/connections between objects in the data call graph
    • graph - full call graph for a data graph view.
    • type_graph - graph results aggregated by object types.
    • complexity_graph - reduced version of a data graph to represent only most complex objects.
    • documents - list documents like post-its attached to a data call graph view.
    • summary - fetch the AI-generated summary attached to the data call graph (if available)
  • advisors - list available code improvement advisors (recommendations) for the application.
  • advisor_occurrences - get occurrences of findings supporting selected advisor for an application.
  • application_database_explorer - explore database tables and columns in an application with three modes:
    • List all tables
    • Filter tables by name
    • Get columns for specific table(s)
  • application_iso_5055_explorer - explore ISO 5055 software quality characteristics (Security, Reliability, Performance, Maintainability) and their associated weaknesses.

Object tools

  • objects - search and filter objects (classes, methods, tables, etc.) in an application. Supports filtering by name, type, and other properties.
  • object_details - get comprehensive details about specific objects with multiple focus options:
    • intra - basic properties and child objects
    • inward - incoming dependencies (callers)
    • outward - outgoing dependencies (callees)
    • testing - fetch related transactions and data graphs.
    • code - source code snippets (when IMAGING_CODE=True in the app.config)
    • insights - quality issues/insights for object
    • documents - fetch attached documents i.e. post-its to an object (if available)
  • add_object_document - attach document (post-its) to an object for knowledge preservation or note taking.
  • source_files - find source files that define code objects, matching a specified file path pattern (contains filter).
  • source_file_details - get detailed dependency analysis for source files with multiple nature options:
    • inventory - all defined code elements
    • intra - internal dependencies within file
    • inward - incoming dependencies to file
    • outward - outgoing dependencies from file
    • testing - elements requiring tests if file changes
  • transactions_using_object - identify all transactions that use a specific object based on a criteria.
  • data_graphs_involving_object - find all data call graphs involving specific objects based on criteria. Essential for understanding data dependencies.

Troubleshooting

  1. Check the MCP Server container is running:
docker ps | grep imaging-mcp
  1. Check MCP Server logs
docker logs <mcp-container-id>

or use the "logs/" folder located in the unzipped installation media folder

or use

  1. Test connectivity to CAST Imaging API:
curl -H "x-api-key: <your-imaging-api-key>" http://<your_imaging_public_URL>:8090/rest/ready
  1. 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
  1. Regenerate API key in CAST Imaging profile if necessary.

Update process

There is no dedicated “in-place” update option, instead you will need to re-run the installation with the new installation media:

  • Download the new installation media for the target release
  • Unzip the installation media.
  • Set the same values in the config/app.config file and .env files located in the new installer directory as done previously for the existing installation.

Then depending on your existing configuration:

For HTTP

  1. Inside the unzipped installer directory, run the following command:
docker rm -f mcp-server        # deletes the existing container
  1. Run the following commands:
chmod +x run.sh         # makes the installation script executable
./run.sh                # run the installation

For HTTPS

  1. Inside the unzipped installer directory, run the following commands:
docker rm -f mcp-server         # deletes the existing container
docker rm -f mcp-nginx-proxy    # deletes the existing container
  1. Create a folder named certificates in the root of the unzipped installation media folder. Inside this folder, add your existing certificate and private key files with the following names:
  • certificate.pem – the secure certificate
  • private_key.pem – the corresponding private key
  1. Run the following commands:
chmod +x run.sh        # makes the installation script executable
./run.sh               # run the installation

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

FAQ

See Frequently Asked Questions.