Query your application with GraphRAG

Overview

GraphRAG builds a semantic knowledge base from the functional documents and source-code context available for a CAST Imaging application. It creates semantic representations of that content, extracts business concepts and their relationships, and can group related concepts into topics. The resulting knowledge graph is stored in the application’s Neo4j database.

You can then ask conceptual and business-oriented questions through an MCP-aware client such as GitHub Copilot, Claude Desktop or Codex App. The CAST Imaging MCP Server searches the generated knowledge graph and combines those semantic results with CAST Imaging’s structural information.

The GraphRAG generation service is included and enabled by default in CAST Imaging.

Compatibility

Querying GraphRAG requires an MCP Server release that matches your CAST Imaging release:

What GraphRAG uses

GraphRAG uses the active documents associated with the application, including:

• AI-generated summaries for Transactions and Data Call Graphs.
• Functional-purpose documents for the objects present in those views.
• Source code associated with those object-purpose documents.
• User-created post-its attached to objects, Transactions and Data Call Graphs.

Functional-purpose text and source code are represented separately. This helps GraphRAG preserve the business meaning of an object while still making relevant implementation details and code snippets discoverable.

GraphRAG uses only the current active version of an object and its documents. When an application is updated and the pipeline is run again, changed and new content is processed while unchanged content can be reused. Content that is no longer current is excluded from semantic search.

How it works

Generation

Before running GraphRAG, generate the AI summaries for the application’s Transactions and Data Call Graphs, from the GraphRAG page in CAST Imaging. These summaries also prepare the functional-purpose and source-code documents used for the objects in those views. See Prepare AI summaries.

Once that is done, run the GraphRAG pipeline from the GraphRAG page. The pipeline:

1. Creates semantic representations of the active application documents and source-code context.
2. Extracts business entities and relationships.
3. Optionally groups related entities into topics.

The generated data is stored in the application’s Neo4j database.

Retrieval

After the pipeline completes, an MCP-aware client queries the knowledge graph through the CAST Imaging MCP Server. Use semantic search for questions such as:

• What business processes are implemented in this application?
• Where is order cancellation handled?
• Which objects contribute to invoice validation?
• What concepts are related to customer onboarding?
• Show the functional context and relevant code for refund processing.
• Which business topics appear in this Transaction or Data Call Graph?

Use CAST Imaging’s structural search for exact questions about application inventories, objects, Transactions, call chains, dependencies, technologies and quality insights.

An MCP client can use both types of search in the same conversation. For example, it can first find a business concept semantically and then use structural information to trace its callers, callees or containing Transaction.

Before you start

Make sure that:

• CAST Imaging and the target application are installed and accessible.
• The application analysis is complete and its data source is configured.
• AI summaries have been generated for the application’s Transactions and Data Call Graphs.
• The GraphRAG service is running and reachable from CAST Imaging.
• Neo4j is reachable from both the GraphRAG service and the CAST Imaging MCP Server.
• The LLM and embedding settings are configured in AI Settings.
• The CAST Imaging MCP Server 3.1.0-beta3 or above is installed if you want to query GraphRAG from an MCP client.

Configure the LLM and embedding providers

Both are configured in AI Settings by a user with the Administrator role:

• LLM provider - used for completion when the pipeline runs.
• Embedding provider and model - used to create the semantic representations of your application documents and source code.

The embedding provider may be the same as, or different from, the LLM provider. For example, you can use Claude AI for generation and OpenAI for embeddings.

Where both use the same provider, CAST Imaging can reuse the stored LLM credentials, although the embedding model name is still required. Where they use different providers, configure separate embedding credentials.

The supported embedding providers, their credential requirements and their default models are listed in AI Settings - GraphRAG.

Prepare AI summaries

Before running GraphRAG:

1. Open the target application in CAST Imaging.
2. Generate the AI summaries for its Transactions and Data Call Graphs from the GraphRAG page - see Generate AI Summary for details about generating summaries, including in bulk. Note that you can also generate these summaries via the GraphRAG tab, described below.
3. Wait for AI-summary processing to complete.
4. Open the GraphRAG tab.

This preparation provides GraphRAG with:

• Functional summaries for Transactions and Data Call Graphs.
• The purpose of the objects participating in those views.
• The source-code context associated with those object-purpose documents.

User-created post-its remain additional context. They do not replace the primary object-purpose document.

Run GraphRAG from the UI

From the landing page select Customize the results for your chosen application:

Then choose the GraphRAG tab:

The configured AI provider and embedding model are displayed at the top of the page for quick reference, together with a Change link back to AI Settings:

1. Confirm that the LLM and embedding settings are configured.
2. Generate the AI summaries for the application’s Transactions and Data Call Graphs if not already complete.
3. Once that is complete, choose whether to run the Entity clustering stage (enabled by default):

5. Click Run Pipeline.

6. Wait until the job status shows complete.

The GraphRAG tab verifies that the service is available, that the required LLM and embedding settings are configured, and that the application data source is available. It may also prevent the pipeline from starting until the required application preparation is complete.

Estimated cost

The AI Summaries section displays an estimated cost for generating the summaries for the objects you have selected, so that you can gauge the spend with your AI provider before starting the run:

The figure is a US dollar range - see Cost estimation for how it is calculated and what it excludes.

Summary run history

The Summary Run History section lists each AI summary generation run for the application:

Entity clustering

Keep Entity clustering enabled when you want GraphRAG to organize related concepts into readable topics and themes.

Clustering is optional. Embedding generation and Entity & Relationship extraction are always run. Because clustering is an additional AI driven stage, it adds to the cost of the run - use the estimate shown on the stage to decide whether to include it.

Pipeline stages

Each stage displays an estimated cost range before you start the run, so that you can see what the selected stages are likely to cost with your AI provider:

See Cost estimation for how each stage figure is calculated.

Cost estimation

Before a run starts, the GraphRAG tab shows an estimated cost as a US dollar range, both for the AI summaries and for each pipeline stage. Two things are worth knowing about these figures:

• They are produced from application metadata. Calculating an estimate does not call an AI model and does not consume billable tokens.
• Each estimate distinguishes the cost of the next run, which excludes work that is already current and can be reused, from the cost of processing everything from scratch.

Estimated tokens are converted to US dollars using the rates of the model that will do the work - the completion model for generation stages, the embedding model for embeddings - as configured in AI Settings:

cost = (input tokens × input rate + output tokens × output rate) / 1,000,000

AI summary estimates

The estimate covers the Transaction and Data Call Graph summaries, and is calculated in two parts:

• Object-purpose analysis - each distinct code object is estimated from its lines of code, the prompt and the expected output. An object whose purpose document is already current is excluded from the next-run estimate, and work shared between objects is deduplicated where possible.
• View summarization - each selected view is estimated from its objects, relationships, prompt chunks, expected summary and final aggregation. Where a reasoning model is used, the reasoning output you are billed for is included.

Recorded usage from the same application is used wherever it is available. Where it is not, the estimate is derived from a sample of the source, from comparable history for other applications, or from the size of the content to process.

Pipeline estimates

The pipeline estimate is the sum of four stages:

Blank and very short text is excluded. Large source documents are split into chunks and can therefore produce several embedding calls.

On an application that has not been processed before, the extraction and clustering figures are projected from the counts of the stages that precede them, and are correspondingly less precise. Once content has been processed, later estimates count the data actually awaiting processing.

Monitor a run

The GraphRAG tab shows the current application status and stage progress. It also provides:

• The current stage and the work completed.
• Run history - see Run history below.
• Overall and stage-level AI token consumption.
• Cancellation for a running job.
• Downloadable logs for a selected run.

Logs can be downloaded while a run is active, but the log for the current stage may be incomplete until that stage finishes.

If a stage completes with failures or warnings, review the logs before relying on the generated results. A retry can continue recoverable work without rebuilding content that is already current.

Run history

The Run History section lists the pipeline runs executed for the application:

In addition to the date, duration, stages and status of each run, the following execution details are provided:

• Input and output tokens consumed.
• The primary AI provider and model used.
• The embedding provider and embedding model used.

Recording the provider and model alongside each run makes it easy to see which configuration produced the knowledge graph currently stored for the application - useful when the embedding configuration has been changed and the graph needs to be rebuilt.

Rerun after an application update

The GraphRAG pipeline is designed to be rerun safely:

• If nothing relevant has changed, completed work is reused and the run can finish quickly.
• If the application contains new or changed objects and documents, GraphRAG processes the new content and refreshes the affected semantic data.
• If a document was edited or removed, its previous semantic representation is no longer returned as current.
• User-created post-its are processed as independent documents and are refreshed when their content changes.

Refresh the application’s AI summaries before rerunning GraphRAG, so that Transaction, Data Call Graph and object-purpose documents represent the current application analysis.

GraphRAG service configuration

The provider, credentials, completion model and embedding model used for generation all come from AI Settings. The following GraphRAG-specific option is available to administrators:

#IMAGING-GRAPH-RAG
GRAPHRAG_PORT=8286

• GRAPHRAG_PORT controls the internal GraphRAG service port.

You can find this option here:

• For CAST Imaging installed on Docker/Podman, in the imaging-viewer .env file located in /opt/cast/installation/imaging-viewer/.env

• For CAST Imaging installed on Microsoft Windows, in the following file: %PROGRAMDATA%\CAST\Imaging\CAST-Imaging-Viewer\setup-config\imaginggraphrag\app.config

The pipeline selects its content from the active application documents, therefore no content-selection setting is required.

Query GraphRAG through the MCP Server

Install the CAST Imaging MCP Server 3.1.0-beta3 or above and enable semantic search in its configuration (app.config on Docker, configuration.conf on Microsoft Windows). The recommended configuration is:

MCP_TOOL_SURFACE_PROFILE=intents
GRAPHRAG_ENABLED=true
NEO4J_URL=bolt://<neo4j-host>:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=<password>

See MCP Server installation on Linux via Docker or MCP Server installation on Microsoft Windows for the location of these options and for the other settings available.

For normal tenant-based operation, the MCP Server reads the embedding provider, model and credentials configured in CAST Imaging AI Settings.

MCP intents mode

intents is the default and recommended MCP tool-surface profile. It gives the AI client a compact search interface instead of exposing every GraphRAG function as a separate top-level tool. See Meta Tool mode for a full explanation, and for the full profile which remains available where you deliberately want every underlying function exposed directly.

With GraphRAG enabled, the MCP client receives four search tools:

• get_structural_search_function_syntax
• run_structural_search_function
• get_semantic_search_function_syntax
• run_semantic_search_function

The client uses the semantic syntax and execution tools to select the appropriate GraphRAG capability. You normally ask questions in natural language and do not need to select these functions manually.

Semantic-search capabilities include:

• Finding code and document context related to a business question.
• Finding extracted business entities by keyword.
• Listing entity types and relationship types.
• Listing or semantically searching entity topics.
• Finding prevalent concepts for an object, Transaction or Data Call Graph.
• Retrieving documents associated with a selected CAST Imaging identifier.
• Checking the GraphRAG configuration and connectivity.
• Adding supplied documentation to the semantic document store when requested.

Recommended setup flow

1. Configure a supported LLM provider in AI Settings.
2. Configure the embedding provider and model in AI Settings.
3. Ensure that the GraphRAG service and the application data source are available.
4. Generate or refresh the Transaction and Data Call Graph AI summaries where the application contains those views.
5. Run the GraphRAG pipeline from the application’s GraphRAG tab.
6. Install and configure the CAST Imaging MCP Server 3.1.0-beta3 or above, setting MCP_TOOL_SURFACE_PROFILE=intents and GRAPHRAG_ENABLED=true.
7. Ask your MCP client to verify GraphRAG connectivity and the embedding configuration.
8. Ask semantic or business-oriented questions about the application.

Troubleshooting

Security consideration

The generated knowledge graph can contain functional documentation, user post-its and source-code-derived context, and semantic search may return relevant code snippets when they answer a question. Protect access to Neo4j, the GraphRAG service and the MCP Server according to your organization’s source-code access policy.

Key rules

• Configure the LLM and embedding settings in AI Settings before running GraphRAG.
• Generate or refresh the Transaction and Data Call Graph AI summaries before running GraphRAG.
• Check the estimated cost shown for the AI summaries and for each pipeline stage before starting a run.
• After changing the embedding provider or model, rerun GraphRAG before using semantic search.
• Use Entity clustering where business topics and themes are useful.
• Use semantic search for business meaning and relevant implementation context.
• Use structural search for exact CAST Imaging objects, dependencies, call paths, Transactions and quality information.
• Rerun GraphRAG after refreshing the AI summaries when the application analysis changes.