MCP server exposing CAST Imaging software architecture insights to AI agents
The CAST Imaging MCP Server bridges the gap between AI agents and real software architecture by exposing comprehensive software intelligence through the Model Context Protocol (MCP). It allows the user to get insights about their applications ,transactions, dependencies, quality patterns, and architectural structures by prompting AI agents.
This service provides AI Agents with the understanding of your applications from portfolio-level inventories to granular object relationships. Whether you're exploring database schemas, analyzing transaction flows, investigating quality issues, the MCP server delivers precise, paginated data that enables informed architectural decisions.
The MCP server should run on a Linux system. CAST Imaging‑APIs may run on the same or a different Linux machine.
curl -H "x-api-key: <your-imaging-api-key>" http://{CONTROL_PANEL_HOST}:8090/imaging/apis/rest/ready
# expected: true
config/app.config and .env../run.sh --install.com.castsoftware.imaging.mcpserver.docker.1.0.2-funcrel/
├─ config/
│ └─ app.config
├─ .env # hidden; use `ls -a`
├─ docker-compose.yml
├─ run.sh
├─ README.md
└─ copilot-instructions.md
Make sure the Control Panel/registry is reachable and Imaging‑APIs is ready (see Quick Start step #1).
Edit config/app.config:
HOST_CONTROL_PANEL="your-control-panel-host" # REQUIRED: Control Panel service registry host/IP
PORT_CONTROL_PANEL=8098 # Default Control Panel registry port
IMAGING_PAGE_SIZE=1000 # Internal fetch batch size
IMAGING_DISPLAY_PAGE_SIZE=20 # Page size in responses
IMAGING_CODE=False # Source code access via MCP (security sensitive)
DEBUG_MODE=false # Debug mode to see the activity in logs
IMAGING_DOMAIN="default" # Imaging domain/tenant
CONTROL_PANEL_SSL_ENABLED=false # Set true only if Control Panel config/eureka is on HTTPS
MCP_TOOL_SURFACE_PROFILE="full" # MCP tool exposure profile: "intents" or "full"
MCP_INTENTS_HIDDEN_FUNCTIONS="" # Comma-separated structural functions hidden from intents mode
SERVICE_HOST="your-service-host" # REQUIRED: The IP/hostname of the machine on which the MCP Server is running
SSL_CA_BUNDLE="" # Optional PEM bundle for private/self-signed CAs
Set your exposed port in .env (hidden file):
MCP_SERVER_PORT=8282
Tip: On Linux, files starting with a dot (like
.env) are hidden. Usels -ato view.
chmod +x run.sh
./run.sh --install
This launches the Docker Compose stack and the MCP server.
If you use SSL_CA_BUNDLE, place the PEM file in a certificates/ folder next to docker-compose.yml. The compose file mounts that folder into the container at /app/certificates.
HOST_CONTROL_PANEL (Required)Default: None (user needs to provide the value)
Description: IP or hostname of the machine running the Control Panel Service.
This is a service registry used by Imaging to register and discover its internal services. It is automatically deployed when you install Imaging. You should enter the IP address of the Linux machine running the Imaging Control Panel service.
PORT_CONTROL_PANELDefault: 8098
Description: Control Panel registry port.
IMAGING_PAGE_SIZEDefault: 1000
Description: Sets the number of records the MCP server fetches per request (internal batching). Tune for throughput.
IMAGING_DISPLAY_PAGE_SIZEDefault: 20
Description: Sets how many records are shown per page in the user-facing response. Tune for UX.
IMAGING_CODEDefault: False
Description: Controls whether the agent can access source code via the MCP server.
It's false by default, as agents typically work on open repos. Enabling it can expose source code to anyone with MCP access, making it a potential security risk, especially relevant for clients like Claude desktop without direct repo access.
DEBUG_MODEDefault: false
Description: Debug mode will show teh activity in the logs. When set to true it will show the tool picked, the API called and the result for each user prompt. When set to false, it will only show the tool picked and the corresponding API called.
IMAGING_DOMAINDefault: default
Description: Imaging domain/tenant used to fetch data in multi-tenant environments.
CONTROL_PANEL_SSL_ENABLEDDefault: false
Description: Set to true when Control Panel config/eureka endpoints run on HTTPS.
MCP_TOOL_SURFACE_PROFILEDefault: full
Description: Selects the MCP tool exposure profile. Use full to expose the complete toolset, or intents for the meta-tool surface.
MCP_INTENTS_HIDDEN_FUNCTIONSDefault: empty
Description: Comma-separated list of structural functions to hide when MCP_TOOL_SURFACE_PROFILE is set to intents.
SERVICE_HOST (Required)Default: None (user needs to provide the value)
Description: IP/hostname of the machine on which the MCP Server is running.
SSL_CA_BUNDLEDefault: empty
Description: Optional path to a PEM CA bundle for private/self-signed certificate chains. With the Docker installer, place the PEM under ./certificates/ and reference it as /app/certificates/<file>.pem.
Start the server with:
chmod +x run.sh
./run.sh --install
This section provides detailed steps for installing and configuring the CAST Imaging MCP Server on Windows systems.
Package contents:
com.castsoftware.imaging.mcpserver.__MCP_VERSION__*/
├─ mcpserver/
├─ tools/
├─ configuration.conf
├─ mcp-server-installer.bat
└─ README.md
Make sure the Control Panel/registry is reachable and Imaging‑APIs is ready:
curl -H "x-api-key: <your-imaging-api-key>"
http://{HOSTNAME_CONTROL_PANEL}:8090/rest/ready
# expected: true
Edit configuration.conf with your environment settings:
HOSTNAME_CONTROL_PANEL="your-control-panel-host" # Required: IP or hostname of Control Panel server
SERVICE_HOST="your-service-host" # Required: IP/hostname of the MCP Server machine
PORT_CONTROL_PANEL=8098 # Default Control Panel registry port
MCP_SERVER_PORT=8282 # Default MCP server port
INSTALL_DIR=C:\Program Files\Cast\Imaging-MCP-Server # Default installation location
CONFIG_DIR=C:\ProgramData\CAST\Imaging-MCP-Server # Default config files location
IMAGING_PAGE_SIZE=1000 # Records per internal request
IMAGING_DISPLAY_PAGE_SIZE=20 # Records per response page
IMAGING_CODE=False # Enable source code access (security consideration)
DEBUG_MODE=false # Debug mode to see the activity in logs
IMAGING_DOMAIN=default # Imaging domain/tenant
CONTROL_PANEL_SSL_ENABLED=false # Set true only if Control Panel config/eureka is on HTTPS
MCP_TOOL_SURFACE_PROFILE=full # MCP tool exposure profile: full or intents
MCP_INTENTS_HIDDEN_FUNCTIONS= # Comma-separated structural functions hidden from intents mode
SSL_CA_BUNDLE= # Optional PEM bundle for private/self-signed CAs
Run the installation using the batch script:
mcp-server-installer.bat --install configuration.conf
This installs the MCP server as a Windows service. After successful installation, you'll see a Windows service named "CAST Imaging MCP Server" in your services list.
Check that the service is running:
To update an existing installation:
mcp-server-installer.bat --update
No configuration changes needed for updates.
To completely remove the MCP server:
mcp-server-installer.bat --uninstall
This removes the Windows service and cleans up all MCP-related files.
For available commands:
mcp-server-installer.bat --help
Available commands:
mcp-server-installer.bat --install configuration.conf : Install CAST Imaging MCP server
mcp-server-installer.bat --update : Update CAST Imaging MCP server
mcp-server-installer.bat --uninstall : Uninstall CAST Imaging MCP server
mcp-server-installer.bat --help : Display help message
| Issue | Possible Cause | Solution |
|---|---|---|
| Service won't start | Configuration error | Check %CONFIG_DIR%/setup-config/app.config |
| Connection refused | Service not running | Restart "CAST Imaging MCP Server" service |
| Installation fails | Insufficient permissions | Run installer as Administrator |
This section provides detailed steps for for connecting the CAST Imaging MCP Server with Github Copilot.
.vscode/mcp.json){
"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://<your-mcp-server-host:port>/mcp/",
"headers": {
"x-api-key": "${input:imaging-key}",
"x-user-tenant": "${input:imaging-tenant}"
}
}
}
}
If VS Code doesn’t auto‑pick the server:
http(s)://<your-mcp-server-host:port>/mcp/ and confirm.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}",
"x-user-tenant": "${input:imaging-tenant}"
}
}
Copy copilot-instructions.md from the installer into your VScode by creating a folder named .github and then pasting the copilot-instructions.md file inside it. This will help the agent in proving better responses.
# MCP container running
docker ps | grep mcp-server
# Imaging‑APIs health
curl -H "x-api-key: <your-key>" http://{CONTROL_PANEL_HOST}:8090/imaging/apis/rest/ready
List all applications
List 5 transactions for application <YourApp>
List available applications datagraphs
List applications insights
The server organizes functionality into Toolsets.
| Toolset | Description |
|---|---|
Portfolio Tools | Portfolio‑level exploration: list applications, compare metrics, scan hotspots across systems. |
Applications Tools | Application‑level analysis: transactions, quality issues, datagraphs, architecture. |
Objects Tools | Object element exploration: locate objects, references, callers/callees. |
| Symptom | Likely Cause | What to do |
|---|---|---|
ECONNREFUSED from client | Server not running | docker ps, then ./run.sh --install to start |
| Auth errors | Wrong/expired Imaging API key | Regenerate key from Imaging profile |
| Empty answers | Imaging‑APIs unreachable | Recheck HOST_CONTROL_PANEL / PORT_CONTROL_PANEL, health endpoint |
| HTTPS handshake/error | Private/self-signed Control Panel certificate | Set CONTROL_PANEL_SSL_ENABLED=true and configure SSL_CA_BUNDLE |
| VS Code not prompting for key | Missing inputs in mcp.json | Add the inputs block (see setup) |
# Server logs
docker logs <mcp-container-id>
# Re‑verify Imaging‑APIs
curl -H "x-api-key: <your-key>" http://{CONTROL_PANEL_HOST}:8090/imaging/apis/rest/ready
IMAGING_CODE = False by default: enabling allows MCP clients to access source code → restrict by policy, network, and credentials.SSL_CA_BUNDLE for private CAs: prefer a CA bundle over disabling TLS verification.com.castsoftware.imaging.mcpserver.docker.__MCP_VERSION__/
├─ config/app.config
├─ docker-compose.yml
├─ run.sh
├─ .env # hidden
├─ README.md # original docs
└─ copilot-instructions.md # optional, copy to .github/
app.config, .env, mcp.json paths and valuesThis repository contains documentation only.
The project’s source code is proprietary and is not published under an open-source license.
For commercial licensing inquiries, please contact your local CAST representative (https://www.castsoftware.com/overview).
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
docker run -i --rm docker.io/castimaging/imaging-mcp-server:3.0.4Merge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"io-github-cast-extend-imaging-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/castimaging/imaging-mcp-server:3.0.4"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup referencedocker.io/castimaging/imaging-mcp-server:3.0.4dockerCAST Imaging MCP Server works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.