MCP Server installation on Linux via Podman

This page covers MCP Server 3.0.x and earlier and has not yet been revised for release 3.1.0, which delivers an MCP Gateway and changes the configuration file, the mounted paths and the published port. Do not follow this page against 3.1.0 installation media - see CAST Imaging MCP Server 3.1 (beta).

This doc explains how to run the CAST Imaging MCP Server Docker installer with Podman.

The standard installer is Docker oriented, but the packaged docker-compose.yml in the installer can also be used with Podman Compose. Some environments need one additional change: when Podman runs on a SELinux-enforcing host, bind-mounted files and folders may need the :Z mount label so the container can read them.

Use the base Podman steps first. Apply the SELinux section only when SELinux is enforcing or when the container cannot read mounted files such as app.config.

Common SELinux-related failure:

Error: /app/server/config/app.config not found

In that case, the file can exist on the host and still be invisible to the container because SELinux blocks access to the bind mount.

Prerequisites

CAST Imaging MCP Server Docker installer.
Podman and Podman Compose installed.
Podman configured for the user running the MCP server. Rootless Podman is supported when the user has permission to run containers and bind the selected port.
CAST Imaging Control Panel reachable from the Imaging MCP server host.
CAST Imaging API service available through Control Panel service discovery.

Check the Podman installation:

podman --version
podman compose version

1. Extract the Installer

Extract the Imaging MCP Server Docker installer and go to the extracted directory:

cd /path/to/com.castsoftware.imaging.mcpserver.docker.<version>

The directory should contain files and folders similar to:

config/app.config
.env
docker-compose.yml
run.sh
README.md
copilot-instructions.md

2. Configure the Imaging MCP Server

Edit config/app.config and set the required values:

HOST_CONTROL_PANEL="your-control-panel-host"
PORT_CONTROL_PANEL=8098
SERVICE_HOST="your-mcp-server-host"
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=""
SSL_CA_BUNDLE=""

Edit .env and set the exposed MCP server port:

MCP_SERVER_PORT=8282

If SSL_CA_BUNDLE is used, place a Base-64 PEM CA bundle under certificates/ and reference it from app.config as /app/certificates/<file>.pem. The PEM must contain the CA certificate chain that issued the HTTPS server certificate, typically intermediate CA certificate(s) plus the root CA certificate, one certificate block per certificate. Do not include private keys.

3. Check Host Folders

The Docker installer normally prepares these folders through the run.sh file. If you start directly with podman compose, check that the mounted paths exist and are readable/writable by the current user:

mkdir -p logs certificates
touch logs/mcp_img.log
chmod 755 logs certificates
chmod 644 logs/mcp_img.log config/app.config .env

If these files and folders already exist with the right permissions, no change is needed.

4. Check Whether SELinux Requires Mount Labels

Check the SELinux status:

getenforce

If the result is Enforcing, update docker-compose.yml and add :Z to the bind mounts. Keep :ro for the certificates mount if it is already read-only.

Use this volume section:

    volumes:
      - ./config/app.config:/app/server/config/app.config:Z
      - ./certificates:/app/certificates:ro,Z
      - ./logs:/app/logs:Z
      - ./.env:/app/server/.env:Z

The rest of the compose file can stay unchanged. A SELinux-compatible compose file should look like this:

services:
  mcp-server:
    image: <image-from-installer>
    container_name: mcp-server
    user: "${HOST_UID}:${HOST_GID}"
    ports:
      - "${MCP_SERVER_PORT}:${MCP_SERVER_PORT}"
    volumes:
      - ./config/app.config:/app/server/config/app.config:Z
      - ./certificates:/app/certificates:ro,Z
      - ./logs:/app/logs:Z
      - ./.env:/app/server/.env:Z
    command:
      - /app/init.sh
    restart: unless-stopped
    networks:
      - mcp-network
networks:
  mcp-network:
    driver: bridge

Do not change the image name unless your environment requires a fully qualified registry name or a different internal registry.

If SELinux is Disabled or Permissive, the standard installer volume section may work as-is:

    volumes:
      - ./config/app.config:/app/server/config/app.config
      - ./certificates:/app/certificates:ro
      - ./logs:/app/logs
      - ./.env:/app/server/.env

5. Export Runtime User Variables

The compose file runs the container with the current host user’s UID and GID. Export these values before starting with Podman:

export HOST_UID="$(id -u)"
export HOST_GID="$(id -g)"

6. Start with Podman Compose

Start the MCP server:

podman compose up -d

If your environment uses podman-compose instead of podman compose, run:

podman-compose up -d

7. Verify the Container

Check that the container is running:

podman ps -a

Check logs:

podman logs mcp-server

Expected successful startup includes messages similar to:

Eureka server is accessible
IMAGINGAPIS is UP
STARTING MCP SERVER
Successfully loaded configuration from: /app/server/config/app.config
Successfully registered with Eureka
Running MCP server with streamable HTTP transport

Check the Imaging MCP health endpoint:

curl http://<mcp-server-host>:<mcp-server-port>/mcpserver/healthcheck

Expected response:

{"status":"healthy","service":"mcp-server"}

Troubleshooting

1. /app/server/config/app.config not found

With Podman on a SELinux-enforcing host, this usually means the bind mount is blocked by SELinux labeling.

Check SELinux:

getenforce

If it returns Enforcing, add :Z to the config/app.config mount:

      - ./config/app.config:/app/server/config/app.config:Z

Then recreate the container:

podman compose down
podman compose up -d

2. Cannot write logs

Make sure logs/ and logs/mcp_img.log are writable by the current user:

mkdir -p logs
touch logs/mcp_img.log
chmod 755 logs
chmod 644 logs/mcp_img.log

If SELinux is enforcing, also confirm the logs mount has the SELinux label:

      - ./logs:/app/logs:Z

3. Image pull fails or Podman asks for short-name resolution

Use the image name provided in the installer compose file. If your Podman configuration requires fully qualified image names, update the image to include the registry explicitly, for example:

    image: docker.io/<repository>/imaging-mcp-server:<tag>

Use the repository and tag supplied with your official installer.

4. Port is already in use

Update MCP_SERVER_PORT in .env, then restart:

podman compose down
podman compose up -d

5. Control Panel or Imaging APIs are not reachable

Verify HOST_CONTROL_PANEL, PORT_CONTROL_PANEL, and SERVICE_HOST in config/app.config.

Also check network access from the host:

curl http://<control-panel-host>:8098/eureka/apps
curl -H "x-api-key: <your-imaging-api-key>" http://<control-panel-host>:8090/imaging/apis/rest/ready