Connect your AI client to the CAST MCP Servers

Connect GitHub Copilot in Visual Studio Code, Claude Code, Claude Desktop or another MCP client to the CAST Imaging and CAST Gatekeeper MCP Servers

Overview

Ask CAST Imaging or CAST Gatekeeper about your applications from the AI client you already use. This page is for developers: it covers what you can ask, how to configure your client and how to check the connection. Any MCP client that supports remote HTTP (streamable HTTP) servers can connect. This page documents the clients tested by CAST:

  • GitHub Copilot in Visual Studio Code
  • Claude Code
  • Claude Desktop

What you can do

Ask in plain language. Your AI client picks the CAST tools, calls them, and combines the results into one answer.

With CAST Imaging

Discover an application

Understand what an application does, how it is built and how it connects to other applications.

Tools: stats, architectural_graph, inter_applications_dependencies

Reduce technical debt

Find the structural flaws, ISO 5055 issues and complexity hotspots that cost the most, and where they are in the code.

Tools: quality_insights, quality_insight_violations, object_details

Check the impact of a change

Before you change a method, a service or a table, see what will break.

Tools: objects, data_graphs_involving_object, transactions_using_object

Maintain and document

Document API endpoints, group transactions by domain and explain data flows end to end.

Tools: transactions, transaction_details, data_graph_details

Speed up modernization

Find microservices candidates, cloud blockers, outdated frameworks and the scope of a migration.

Tools: advisors, quality_insights, packages

With CAST Gatekeeper

Check compliance

See where an application stands on ISO 5055 and your quality gates, snapshot by snapshot.

Tools: list_applications, get_compliance_status

Track violations and debt

Find security and quality violations, measure technical debt and follow trends across snapshots.

Tools: get_violations, get_technical_debt, get_objects

Manage action plans

Add violations to the action plan, or exclude them, without leaving your AI client.

Tools: get_violations, manage_action_plan, manage_exclusion

Prompts you can try

Start with one prompt per use case. Replace <APP_NAME> with one of your applications, then copy the prompt into your AI client:

Product Use case Prompt Level
Imaging Discover an application What does <APP_NAME> actually do? Walk me through its main components, layers and how they connect. Simple
Imaging Reduce technical debt Where are the most critical structural flaws in <APP_NAME> that hurt reliability, performance or security? Intermediate
Imaging Check the impact of a change If I change or remove the <TABLE_NAME> table in <APP_NAME>, what will break? Intermediate
Imaging Maintain and document Group the transactions in <APP_NAME> by functional domain. Intermediate
Imaging Speed up modernization What blocks <APP_NAME> from moving to the cloud? Show me the exact objects. Intermediate
Gatekeeper Check compliance Assess ISO-5055 compliance for <APP_NAME>. Simple
Gatekeeper Track violations and debt Show quality trends for <APP_NAME> across the last 3 snapshots. Intermediate
Gatekeeper Manage action plans Add the critical security violations in <APP_NAME> to the action plan. Intermediate

For more examples, see CAST Imaging MCP and CAST Gatekeeper MCP.

Quick start

  1. Get your values. The configurations on this page use the following placeholders:
    • <CAST_URL> - the URL you use to open CAST Imaging, i.e. the machine on which the imaging-services component is installed, for example http://imaging.corp.mycompany.com:8090 or https://imaging.corp.mycompany.com. Use https if HTTPS is enabled; the port is 8090 by default in http mode and can be omitted when https runs on port 443. Do not point your client at the MCP Server machine directly: CAST Imaging routes the requests.
    • <CAST_API_KEY> - your CAST Imaging API key, generated in your profile. The same key works for both MCP Servers. Each user has only one key: if you already have one, reuse it, because generating a new key invalidates the old one immediately and anything still using it stops working.
    • <TENANT> - optional: the name of the target domain (tenant), only when domain mapping is enabled. If you only have one domain (tenant), remove the x-user-tenant header entirely.
  2. Add CAST to your AI client. Pick your client in Client setup and copy its configuration into the file shown. Results depend on the model your client uses - see Recommended LLMs.
  3. Ask a first question. Try List all applications. If you see your applications, you are connected - see Test your connection.

Each MCP Server has its own endpoint on the same <CAST_URL>:

MCP Server URL
CAST Imaging <CAST_URL>/mcp
CAST Gatekeeper <CAST_URL>/mcp/gatekeeper

Client setup

CAST has tested GitHub Copilot in Visual Studio Code, Claude Code and Claude Desktop. Other MCP clients that support remote HTTP servers can connect with the same URLs and headers, but CAST has not yet tested them and does not document their configuration.

Each configuration below declares both MCP Servers: keep only the entries for the servers your administrator has installed.

Install the GitHub Copilot extension (see GitHub Copilot on the Visual Studio Marketplace external link) in Visual Studio Code, sign in to GitHub and open the repository you need to work with.

Create an mcp.json file in the .vscode/ folder of your workspace, or use MCP: Open User Configuration:

{
  "inputs": [
    {
      "id": "cast-api-key",
      "type": "promptString",
      "description": "CAST Imaging API key",
      "password": true
    },
    {
      "id": "cast-tenant",
      "type": "promptString",
      "description": "CAST Imaging domain (tenant)"
    }
  ],
  "servers": {
    "imaging": {
      "type": "http",
      "url": "<CAST_URL>/mcp",
      "headers": {
        "x-api-key": "${input:cast-api-key}",
        "x-user-tenant": "${input:cast-tenant}"
      }
    },
    "gatekeeper": {
      "type": "http",
      "url": "<CAST_URL>/mcp/gatekeeper",
      "headers": {
        "x-api-key": "${input:cast-api-key}",
        "x-user-tenant": "${input:cast-tenant}"
      }
    }
  }
}

Visual Studio Code prompts for the API key and the domain (tenant) when the server first starts, and stores them in its secret storage. If you only have one domain (tenant), remove the cast-tenant input and the x-user-tenant lines. To avoid the prompt, replace ${input:cast-api-key} with the key itself - in that case, do not commit the file.

After changing the domain (tenant), click Restart above the server entry to reconnect: no MCP Server restart is needed.

OAuth: remove the inputs block and the x-api-key headers. Start the server using the gutter action in mcp.json, click Allow, then sign in with your CAST Imaging credentials on the Keycloak page that opens.

If Visual Studio Code does not pick up the server:

  1. Open Copilot Chat → gear icon → Select tools that are available to chat.
  2. Click + Add More Tools… → + Add MCP Server… → choose HTTP.
  3. Enter <CAST_URL>/mcp and confirm.
  4. Visual Studio Code creates .vscode/copilot/mcp.json: add the headers block shown above to the new entry.

Open Chat and select Agent mode: the CAST tools are listed in the tool picker.

Create a .mcp.json file at the root of your project folder:

{
  "mcpServers": {
    "imaging": {
      "type": "http",
      "url": "<CAST_URL>/mcp",
      "headers": {
        "x-api-key": "${CAST_API_KEY}",
        "x-user-tenant": "${CAST_TENANT}"
      }
    },
    "gatekeeper": {
      "type": "http",
      "url": "<CAST_URL>/mcp/gatekeeper",
      "headers": {
        "x-api-key": "${CAST_API_KEY}",
        "x-user-tenant": "${CAST_TENANT}"
      }
    }
  }
}
  • Claude Code replaces ${CAST_API_KEY} and ${CAST_TENANT} with the values of these environment variables: set them before you start Claude Code, so that the file contains no API key and can be committed.
  • If you only have one domain (tenant), remove the x-user-tenant lines.
  • .mcp.json must be at the project root, not in the .claude/ folder. The first time Claude Code finds it, it asks you to approve the servers it declares.

To make the servers available in all your projects instead, add them from a terminal with --scope user. Claude Code stores them in ~/.claude.json:

$ claude mcp add --transport http --scope user imaging <CAST_URL>/mcp --header "x-api-key: <CAST_API_KEY>" --header "x-user-tenant: <TENANT>"
$ claude mcp add --transport http --scope user gatekeeper <CAST_URL>/mcp/gatekeeper --header "x-api-key: <CAST_API_KEY>" --header "x-user-tenant: <TENANT>"

Place the --header options after the URL.

OAuth: omit the x-api-key header. Run claude, enter /mcp, select the server, then Authenticate, and sign in with your CAST Imaging credentials on the Keycloak page that opens.

Confirm the connection:

$ claude mcp list

Claude Desktop reaches a remote MCP server through the mcp-remote bridge, which npx downloads and runs: a local installation of Node.js external link is required.

Edit claude_desktop_config.json (Settings → Developer → Edit Config):

  • Microsoft Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

The file may already contain Claude Desktop settings: add the mcpServers block to the existing content rather than replacing the file.

{
  "mcpServers": {
    "imaging": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<CAST_URL>/mcp",
        "--header",
        "x-api-key:${CAST_API_KEY}",
        "--header",
        "x-user-tenant:${CAST_TENANT}",
        "--transport",
        "http-only",
        "--allow-http"
      ],
      "env": {
        "CAST_API_KEY": "<CAST_API_KEY>",
        "CAST_TENANT": "<TENANT>"
      }
    },
    "gatekeeper": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "<CAST_URL>/mcp/gatekeeper",
        "--header",
        "x-api-key:${CAST_API_KEY}",
        "--header",
        "x-user-tenant:${CAST_TENANT}",
        "--transport",
        "http-only",
        "--allow-http"
      ],
      "env": {
        "CAST_API_KEY": "<CAST_API_KEY>",
        "CAST_TENANT": "<TENANT>"
      }
    }
  }
}
  • -y lets npx install mcp-remote without asking for confirmation, which Claude Desktop cannot give.
  • The env block holds the values that mcp-remote substitutes into the ${...} headers. Do not add a space after the colon in x-api-key: or x-user-tenant:.
  • If you only have one domain (tenant), remove the x-user-tenant header (both args lines) and CAST_TENANT.
  • --allow-http is required only when <CAST_URL> uses http.

Restart Claude Desktop after saving the file.

Instruction files

The installation media of each MCP Server provides instruction files that you can copy into the repository you are working with, so that your AI client receives guidance tailored to CAST. The additional information is not displayed in the chat, but the client uses it to generate higher quality responses.

CAST Imaging MCP Server

Copy copilot-instructions.md from the root of the unzipped installation media into a .github/ folder at the root of your repository. It is optional but recommended: it explains how the MCP Server tools fit together, which improves the answers and stops the client inventing function names. Copy it again after each MCP Server update, as the update refreshes the copy in the installation media but not the one in your repository.

The installation media provides this file for GitHub Copilot only: there is no equivalent for other clients.

CAST Gatekeeper MCP Server

The instructions explain when to use the Gatekeeper tools (compliance status, technical debt, violations, objects, action plans and exclusions), describe the parameters each tool accepts, and provide example prompts. All the files contain the same instructions, shipped under several filenames so that each client loads them automatically. Copy the file matching your client:

Client File Location in your repository
GitHub Copilot (VS Code) copilot-instructions.md .github/copilot-instructions.md
Claude Code CLAUDE.md Repository root
Gemini CLI / Gemini Code Assist GEMINI.md Repository root
Cursor cursor-rules.mdc .cursor/rules/

The installation media provides no AGENTS.md file for OpenAI Codex. Claude Desktop does not use an instruction file.

Test your connection

  1. Launch your AI client, and enter your API key if prompted.
  2. Ask List all applications.
  3. For CAST Imaging, continue with:
List 5 transactions for application <APP_NAME>
List available applications datagraphs
List applications insights

For CAST Gatekeeper, continue with:

Show me the compliance status for <APP_NAME>
How many days of technical debt does <APP_NAME> have?
List the top 10 security violations for <APP_NAME>

The connection works if you receive application listings, architectural insights, compliance or quality metrics, or violation details. Otherwise:

What you see What to check
Connection error The URL: host, port, http or https, and the path (/mcp or /mcp/gatekeeper). Check that your machine can reach CAST Imaging.
Authentication error Your API key. If it is lost or invalid, generate a new one in your profile - this invalidates your previous key, so update every client that used it.
Empty answers The domain (tenant) name in x-user-tenant. Ask your administrator to check that the MCP Server is healthy - see Update and troubleshoot.
CAST Imaging or CAST Gatekeeper tools are missing Each product has its own MCP Server. Ask your administrator which ones are installed.
Too many tools for your client CAST Imaging only: ask your administrator about Meta Tool mode.