Connect your AI client to the CAST 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
Your CAST administrator must install the MCP Server for each product you want to query - see For admins. To choose between the two MCP Servers, see Which MCP Server do I need?.
Your AI client sends the result of each tool call to the LLM it uses. Results include object names, dependencies and quality findings, and can include source code: CAST Gatekeeper includes source snippets in its violation findings by default, and CAST Imaging includes source code only when your administrator enables it. Check that this fits your organization’s AI policy - see the FAQ.
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
Understand what an application does, how it is built and how it connects to other applications.
Tools: stats, architectural_graph, inter_applications_dependencies
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
Before you change a method, a service or a table, see what will break.
Tools: objects, data_graphs_involving_object, transactions_using_object
Document API endpoints, group transactions by domain and explain data flows end to end.
Tools: transactions, transaction_details, data_graph_details
Find microservices candidates, cloud blockers, outdated frameworks and the scope of a migration.
Tools: advisors, quality_insights, packages
With CAST Gatekeeper
See where an application stands on ISO 5055 and your quality gates, snapshot by snapshot.
Tools: list_applications, get_compliance_status
Find security and quality violations, measure technical debt and follow trends across snapshots.
Tools: get_violations, get_technical_debt, get_objects
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
- 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 theimaging-servicescomponent is installed, for examplehttp://imaging.corp.mycompany.com:8090orhttps://imaging.corp.mycompany.com. Usehttpsif HTTPS is enabled; the port is8090by default inhttpmode and can be omitted whenhttpsruns on port443. 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 thex-user-tenantheader entirely.
- 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.
- 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 |
The configurations below use an API key, sent in the x-api-key header. With CAST Imaging 3.6.6-funcrel or later, Claude Code and Visual Studio Code can instead sign in through the browser using OAuth: the OAuth configuration is the same minus the x-api-key header. Your administrator must first enable it - see Security and OAuth. OAuth handles the sign-in only: when domain mapping is enabled, keep the x-user-tenant header.
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.
Do not commit a configuration file that contains your API key to a source code repository. Use a prompt or an environment variable instead, as shown below.
Install the GitHub Copilot extension (see GitHub Copilot on the Visual Studio Marketplace ) 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:
- Open Copilot Chat → gear icon → Select tools that are available to chat.
- Click + Add More Tools… → + Add MCP Server… → choose HTTP.
- Enter
<CAST_URL>/mcpand confirm. - Visual Studio Code creates
.vscode/copilot/mcp.json: add theheadersblock 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-tenantlines. .mcp.jsonmust 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 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>"
}
}
}
}
-yletsnpxinstallmcp-remotewithout asking for confirmation, which Claude Desktop cannot give.- The
envblock holds the values thatmcp-remotesubstitutes into the${...}headers. Do not add a space after the colon inx-api-key:orx-user-tenant:. - If you only have one domain (tenant), remove the
x-user-tenantheader (bothargslines) andCAST_TENANT. --allow-httpis required only when<CAST_URL>useshttp.
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
- Launch your AI client, and enter your API key if prompted.
- Ask
List all applications. - 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. |