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

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.

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.

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 .env file) 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-viewer component 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-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

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

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 Developers strategy: semantic search is available for every application when the global license key includes GraphRAG.
  • Named Application strategy: 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

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.

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:

  1. Open the .env file.
  2. Add a HOST_AUTH_SERVICE line, 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.
  3. Optionally, set the existing PORT_AUTH_SERVICE line to the port of the auth service. When it is left empty, MCP Server reads the port from the Control Panel registry.
  4. Keep HOST_CONTROL_PANEL set to the Control Panel host.
  5. Run the installation (see Step 4 - Run the installation), or restart an existing installation (see Change the configuration after installation).

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., 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 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>/
├── .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.

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

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.

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:

  1. Open the .env file in the installation folder with a text editor:

    <installer-root>/.env
    
  2. Set the option for the MCP server to false to turn it off, or to true to turn it back on, and save the file. For example, to turn off Text2Cypher:

    TEXT_TO_CYPHER_MCP_ENABLED=false
    
  3. Apply the change:

    $ ./run.sh --restart
    
  4. Check the result:

    $ ./run.sh --status
    

    Each MCP server is listed with whether it is enabled and healthy, and how many tools it exposes.

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