MCP Server 3.1 installation on Linux via Docker

Overview

This guide covers the installation of CAST Imaging MCP Server 3.1.0-beta4 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  includes an installation script and configuration files. All Docker images are pulled direct from https://hub.docker.com  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:

• TCP port 8285 must be reachable from the machine hosting CAST Imaging, which is where MCP requests are redirected from - this is the MCP Aggregator Gateway port and the only port published on the host. You can change it in the .env file (see below). Your MCP-aware clients do not connect to this port and do not need access to it. AI Mode also requires this port to be reachable from the machine on which the imaging-viewer component is installed
• 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 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-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.

Recommended LLMs

Multiple LLM providers are supported; however, not all models perform equally when it comes to tool invocation, reasoning, and response reliability. During internal testing, the Claude Haiku 4.5 and Claude Sonnet 4/4.5 models consistently delivered the best results, especially for a wide range of user queries, from simple to highly complex, with strong consistency and minimal hallucinations. Findings are listed below:

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-beta4.
• -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/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

run.sh creates four 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
└── backups/                # Configuration archived by "./run.sh --update"

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=                                          # Set by the installer: registry and repository holding the container image. Change only to install from a different registry.
MCP_IMAGE_TAG=                                        # 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
CONTROL_PANEL_SSL_ENABLED=false                       # When set to true, allows communication with a CAST Imaging instance which is configured to use HTTPS.
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_ENABLED=true                                # Enables local telemetry for MCP tool calls, written in JSON Lines (JSONL) format below the component log folder. Default is "true".
TELEMETRY_PUSH_ENABLED=true                           # Periodically pushes the local telemetry log to CAST. Set to false to keep telemetry on the local host only. No effect when TELEMETRY_ENABLED=false.
TELEMETRY_PUSH_INTERVAL_MINUTES=120                   # Defines how often the 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 - 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 ) 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"
    },
    {
      "id": "imaging-tenant",
      "type": "promptString",
      "description": "Imaging tenant"
    }
  ],
  "servers": {
    "imaging": {
      "type": "http",
      "url": "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp",
      "headers": {
        "x-api-key": "${input:imaging-key}",
        "x-user-tenant": "${input:imaging-tenant}"
      }
    }
  }
}

where:

• "imaging-key" is your CAST Imaging API key (you will be prompted for this)
• "imaging-tenant" is the name of the target domain (tenant) - see domain mapping - you will be prompted for this. This item is optional and can be omitted entirely (remove the x-user-tenant line as well) if you only have one domain (tenant).
• "url" is the IP address/FQDN and port number (8090 by default in http mode) of the machine on which the CAST Imaging imaging-services component is installed. If HTTPS mode has been configured on CAST Imaging for end-user access, use https://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp.

If you prefer not to be prompted for the CAST Imaging API key, or the optional domain (tenant) name, you can “hardcode” them in the mcp.json file as follows, replacing <imaging-key> and <domain/tenant-name> in the headers entry with appropriate values:

{
  "inputs": [
    {
      "id": "imaging-key",
      "type": "promptString",
      "description": "CAST Imaging API Key"
    },
    {
      "id": "imaging-tenant",
      "type": "promptString",
      "description": "Imaging tenant"
    }
  ],
  "servers": {
    "imaging": {
      "type": "http",
      "url": "http[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp",
      "headers": {
        "x-api-key": "<imaging-key>",
        "x-user-tenant": "<domain/tenant-name>"
      }
    }
  }
}

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]://<fqdn-or-IP-address-imaging-services-machine:[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[s]://<fqdn-or-IP-address-imaging-services-machine:[port]>/mcp/",
  "headers": {
    "x-api-key": "${input:imaging-key}",
    "x-user-tenant": "${input:imaging-tenant}"
  }
}

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

Choosing which MCP servers run

The .env file is the single place which decides which MCP servers run. Each setting also controls whether the gateway exposes that MCP server’s tools:

STRUCTURAL_MCP_ENABLED=true
SEMANTIC_MCP_ENABLED=true
TEXT_TO_CYPHER_MCP_ENABLED=true

Set a value to false and apply the change with ./run.sh --restart. 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.

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

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.

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.

Semantic search and natural-language queries are also available through the same endpoint:

Where is the payment authorization logic implemented in Shopizer?

Which components in Shopizer deal with customer address validation?

How many transactions does the Shopizer app have?

Which objects in Shopizer are called by more than ten other objects?

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_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
• applications_transactions - retrieve transactions across all applications available in CAST Imaging with optional filtering.
• inter_app_detailed_dependencies - get detailed dependency information between two specific applications showing exact interaction points.
• inter_applications_dependencies - analyze dependencies between applications showing inward (apps depending on this) and outward (apps this depends on) relationships.

Application tools

• add_view_document - add document (i.e. post-its) to transactions or data graphs for knowledge capture.
• advisors - get migration/modernization advisors, advisor rules, and violations for an advisor for an application. Includes the following focus options:
  • list - list all available advisors for the application.
  • rules - get rules for a specific advisor.
  • violations - get objects violating a specific rule in an advisor.
• 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.
• 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.
• custom_node - manage custom nodes within a custom view to group objects by specific criteria. Allows filtering by transaction, object type and insight.
• custom_views - manage custom aggregation views for grouping objects by custom criteria. Includes options to list, create, get details, delete, update, publish, or unpublish views.
• 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)
• data_graphs - fetch data call graph views for an application with optional filtering capabilities.
• package_interactions - analyze interactions between different packages for an application to understand dependency relationships with it.
• packages - list external packages, libraries or dependencies used by the 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.
• quality_insights - retrieve quality issues and vulnerabilities including CVE, cloud patterns, green patterns, structural flaws, and ISO-5055 violations for an application.
• stats - get basic statistics for an application including size, complexity, and technology metrics.
• 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)
• transactions - fetch transactions for an application with optional filtering capabilities by name or type of the transaction.
• views - manage saved views for an application with options to list all views, create new views with selected objects, update existing views, get complete view details, or delete them.

Object tools

• add_object_document - attach document (post-its) to an object for knowledge preservation or note-taking.
• data_graphs_involving_object - find all data call graphs involving specific objects based on criteria. Essential for understanding data dependencies.
• manage_object_tags - add or delete tags on code elements (objects) in an application. Allows specifying multiple tags to append or remove for a list of object IDs.
• 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)
• object_profiles - get metric profiles per object type for an application, such as the average, minimum and maximum number of code lines or cyclomatic complexity. Returns one aggregate per object type, not values for individual objects - use objects with a metric for those.
• objects - search and filter objects (classes, methods, tables, etc.) in an application. Supports:
  • filtering by name, fullname, type, mangling, filepath or annotation with the contains (default), equals, startswith or endswith operator. All filters in one query must use the same operator, e.g. name:contains:Order,type:contains:Method.
  • restricting results to internal or external objects with searchtype:eq:internal or searchtype:eq:external.
  • filtering by tags.
  • filtering and sorting by an integer metric, such as Cyclomatic Complexity, Number of code lines, Number of Commented Code Lines or Efferent Coupling (CE). Results can be sorted highest or lowest first, or limited with a threshold (greaterThan, lessThan, greaterThanEqualTo, lessThanEqualTo or equals), and each object is returned with its metric value. A metric can be combined with type, searchtype and tags, and with name or fullname using contains only (case-sensitive). It cannot be combined with mangling, filepath or annotation.
    Available in ≥ 3.1.0-beta3 with CAST Imaging ≥ 3.6.6-funcrel
• 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
• source_files - find source files that define code objects, matching a specified file path pattern (contains filter).
• transactions_using_object - identify all transactions that use a specific object based on a criteria.

Semantic search and Text2Cypher tools

The tools of all enabled MCP servers are presented through the single gateway endpoint, in addition to the structural tools listed above. Your client does not need to know which MCP server answered a request.

• Semantic search tools answer meaning-based questions using the CAST Imaging knowledge graph and its embeddings - the purpose of a component, the business concepts it implements, and where a given behaviour is implemented. They cover entity and entity-cluster discovery, retrieval of the code context relevant to a question, and the source documents backing an answer. See Query your application with GraphRAG for the underlying feature. When SEMANTIC_MCP_CONVERSATIONAL_MEMORY_ENABLED=true, additional tools let an agent analyse, persist, search, list and deactivate knowledge gathered during a conversation, scoped to the application it was captured for.
• Text2Cypher tools turn a natural-language question into a graph query against the CAST Imaging knowledge graph, and return the result together with links back into CAST Imaging. They also allow saved ad-hoc queries to be listed and managed, and expose an activity history of the queries which have been run.

Troubleshooting

Start with the status and log commands, which name the failing component:

./run.sh --status
./run.sh --logs

Also check that the "url" parameter in the client mcp.json points to the correct URL, and regenerate your API key in the CAST Imaging profile if necessary.

To test connectivity to the CAST Imaging API:

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

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

$ cat root.crt intermediate.crt > my_cert.pem

-----BEGIN CERTIFICATE-----
(Base64 encoded data)
-----END CERTIFICATE-----

<installer-root>/certificates/my_cert.pem

SSL_CA_BUNDLE=/opt/cast/mcp-suite/certificates/my_cert.pem

./run.sh --restart

Updating configuration after installation

To change a configuration option (for example IMAGING_CODE, LOG_LEVEL, 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:

<installer-root>/.env

2. Change the required setting(s) and save the file.
3. Apply the change:

./run.sh --restart

Update process

The installation media includes a dedicated update option that performs an in-place update to this release:

• Ensure your target CAST Imaging release meets the minimum for this MCP Server release - see CAST Imaging compatibility
• Download the installation media for the target release
• Unzip the installation media next to, not over, the existing installation
• Set NEO4J_URL in the new .env file before you run the update - this setting is now required and cannot be carried over when the existing installation did not define it
• Set SERVICE_HOST in the new .env file to the IP address, hostname, or FQDN of the machine where MCP Server is installed (the current machine). Important: do not set this as “localhost”
• Run the following commands:

chmod +x run.sh                             # makes the installation script executable
./run.sh --update /path/to/old/installer    # run the installation script and update the existing installation

What does the update do?

• Validates the new installation media and pulls the new container image before anything is stopped.
• Archives your existing docker-compose.yml, .env, config/app.config, run.sh and README.md under <old installer>/backups/pre-mcp-suite-<timestamp>/.
• Builds a new .env from this release’s template and carries your existing settings across, including those which have been renamed - see the table below.
• Stops the old container and installs the new files in the existing installation folder.
• Starts the new container and waits for the gateway and every enabled MCP server to become ready.
• Rolls back if the startup fails: the new container is stopped, the archived files are restored, and your previous container image is started again. The previous image is never deleted, so a rollback always has something to return to.

Settings renamed by the update

Your old config/app.config file is no longer read by anything and is kept in the backup folder only.

Post-update action items

• No client reconfiguration is required: your MCP-aware clients continue to connect to CAST Imaging exactly as before.
• Open TCP port 8285 in your firewall rules so that it is reachable from the machine hosting CAST Imaging. Client machines do not need access to this port.
• Your previous MCP_TOOL_SURFACE_PROFILE value is applied to both STRUCTURAL_MCP_TOOL_SURFACE_PROFILE and SEMANTIC_MCP_TOOL_SURFACE_PROFILE in the deployed .env file. To continue exposing all tools directly, set both to full and restart the MCP Server with ./run.sh --restart.
• Telemetry is pushed to CAST every two hours by default. Set TELEMETRY_PUSH_ENABLED=false in the .env file to keep telemetry on the local host only - see Frequently Asked Questions.

Uninstall process

To remove only MCP Server related items:

• stop and remove the container
• delete the installer ZIP file
• delete the unzipped installation files/folder

cd /<unzipped-install-files>
./run.sh --stop

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

FAQ

See Frequently Asked Questions.