CAST Imaging MCP Server Extension

Manage the CAST Imaging MCP Suite directly from VS Code. The extension installs one Docker container and exposes one MCP Gateway endpoint to VS Code, GitHub Copilot, Claude Code, and other MCP clients.

Architecture

VS Code / Claude Code
        |
        | http://<SERVICE_HOST>:<MCP_GATEWAY_PORT>/mcp/
        v
MCP Gateway (public port 8285)
        ├── Structural MCP (internal port 8282)
        ├── Semantic Search MCP (internal port 8287)
        └── Text2Graph MCP (internal port 8289)

The extension pins MCP Suite 3.1.0-beta6, which requires CAST Imaging API 3.6.5 or later.

Prerequisites

• VS Code 1.74 or later.
• Docker with the docker compose plugin.
• CAST Imaging API 3.6.5 or later.
• Network access from Docker to the CAST Imaging Control Panel and Neo4j.
• A CAST Imaging API key.

Quick start

1. Install the extension.
2. Run CAST Imaging MCP: Configure MCP Server.
3. Set:
   • Service Host: the machine where this Docker container runs, normally localhost.
   • Host Control Panel: the machine where CAST Imaging Control Panel runs.
   • Neo4j URL: the Bolt URL reachable from the container.
4. Run CAST Imaging MCP: Install MCP Server.
5. Run CAST Imaging MCP: Start MCP Server.
6. Enter your CAST Imaging API key and tenant when VS Code connects.

The two host settings are intentionally different:

SERVICE_HOST=localhost
HOST_CONTROL_PANEL=imaging.company.internal

MCP clients connect to SERVICE_HOST:8285. The suite uses HOST_CONTROL_PANEL:8098 internally to discover CAST Imaging services.

Configuration

Ports 8282, 8287, and 8289 are reserved for the bundled backends and cannot be selected as the Gateway port.

Semantic embedding-provider configuration is tenant-managed in CAST Imaging/Neo4j. It is not configured by this extension.

Generated installation files

The container installation is stored in VS Code global storage:

mcp-server/
├── .env
├── docker-compose.yml
├── mcp_servers.json
├── certificates/
├── data/
└── logs/

• .env is the single customer-facing suite configuration.
• mcp_servers.json defines routing from the Gateway to the three internal backends.
• logs/ and data/ survive restarts, reinstalls, and force cleanup.
• Place private CA files in certificates/ and configure their container path under /opt/cast/mcp-suite/certificates.

The extension also merges a CASTImaging entry into the workspace's .vscode/mcp.json without removing unrelated inputs or MCP servers:

{
  "inputs": [
    {
      "id": "imaging-key",
      "type": "promptString",
      "description": "CAST Imaging API Key",
      "password": true
    },
    {
      "id": "imaging-tenant",
      "type": "promptString",
      "description": "CAST Imaging tenant"
    }
  ],
  "servers": {
    "CASTImaging": {
      "type": "http",
      "url": "http://localhost:8285/mcp/",
      "headers": {
        "x-api-key": "${input:imaging-key}",
        "x-user-tenant": "${input:imaging-tenant}"
      }
    }
  }
}

Commands

Upgrading legacy beta3 installations

The beta3 extension exposed the standalone Structural MCP on port 8282. The current suite uses the Gateway architecture introduced in beta4 and exposes it on port 8285.

During install or reinstall, the extension:

1. Stops the existing container.
2. Detects a beta3 Compose file.
3. Copies the old Compose, .env, and config/app.config files under backups/pre-beta4-<timestamp>/.
4. Generates the current suite files pinned to 3.1.0-beta6.
5. Updates the workspace's .vscode/mcp.json to the Gateway URL.

Existing logs are retained. The legacy config/app.config is no longer mounted because beta4 uses the suite .env.

An explicitly customized legacy imagingMcp.serverPort is carried forward as the Gateway port. The old default 8282 cannot be carried forward because it is now the internal Structural MCP port, so the extension safely uses 8285 and displays a warning instead. Legacy hidden-function settings continue to apply only to Structural MCP, matching their original purpose.

Existing .github/copilot-instructions.md content is never silently replaced. When newer CAST instructions are available, the extension asks first and creates a timestamped backup before an approved update.

Status and troubleshooting

Check Server Status reports the Gateway plus each backend. A running Docker container is not considered healthy until every enabled backend answers its health endpoint.

Common checks:

docker compose ps
docker compose logs --tail=100
curl http://localhost:8285/mcp/status

Security

• API keys used by VS Code are handled through MCP input prompts.
• Claude Code API keys are stored in VS Code SecretStorage.
• Claude Code is invoked without a command shell, so URL, API-key, and tenant values cannot be interpreted as shell commands.
• Neo4j passwords are stored in VS Code SecretStorage. Existing plaintext settings are migrated automatically and removed. The password is written only to the installation .env required by Docker, which is created with owner-only permissions where supported.
• Source code retrieval is disabled by default.
• Only the Gateway port is published; backend MCP ports remain internal.