illumex Model Context Protocol (MCP) is designed to interpret natural language queries (prompts) from illumex built-in agents or context from 3rd party agents, manage conversational state, and orchestrate the discovery and utilization of both business-semantic and physical data assets. The MCP’s core function is to establish and maintain the context required for accurate AI-driven data interactions, ensuring seamless translation from natural language to executable data commands (like SQL) or matching context retrieval.

Core Functions

The MCP exposes key functions that facilitate contextual data interaction and entity discovery:

• Agentic Data Analytics (Omni)
• Get Semantic Entities
• Get Data Entities
• Get Lineage of an Element
• Get Connected Semantic Elements
• Get Connected Data Elements
• Omni Context History 
• Get SQL Queries 
• Get SQL Query’s data objects

Agentic Data Analytics (Omni)

Purpose: To process a natural language question (prompt), utilize metadata to automatically generate the appropriate SQL query, execute it against the data source, and return the results. This is the protocol’s primary calculation engine.

Request Example:

JSON

{
  "question": "What are the total sales by region for the last quarter?"
}

Get Semantic Entities 

Purpose: To retrieve rich, contextual information about semantic entities (Business Terms, Metrics, Attributes, Analyses) matching a given name. These entities form the semantic context of the data model.

Detail	Description
Endpoint	GET /mcp/semantic-entities
Input	Search term: string, is_certified_only: bool
Output	name, type, description, certified status, owners, tags, modified by, created by, queries, dashboards, visuals, usage, tables, columns

Response Example (Key Contextual Fields):

JSON

          
{
  "entities": [
    {
      "name": "Total Revenue",
      "type": "metric",
      "description": "Total revenue calculated as sum of all sales transactions excluding returns and discounts",
      "certified": true,
      "certification": { ... },
      "usage": { "count": 245, "lastUsed": "2024-03-15T14:22:00Z" }, 
      "relatedEntities": [ ... ]
    }
  ]
}

Get Data Entities 

Purpose: To find the physical data elements (columns, tables, BI assets) that underpin the semantic layer. These entities define the physical data context.

Detail	Description
Endpoint	GET /mcp/data-entities
Input	Search term
Output	Data object’s name, type, description, owners, tags, modified by, created by, usage, tables, columns, duplications status, last queried, queries list, joins list, aliases, related semantic objects

Get Lineage of an Element

Purpose: To find the physical data elements (columns, tables, BI assets) dependent on or dependent on the specific data element (downstream and upstream). Currently supports one level.

Detail	Description
Endpoint	GET /mcp/lineage/:id
Input	Data element id
Output	Data object with identifier of lineage level and  2 lists (upstream and downstream) of data object’s id, name, connector, tags, columns.

Get Connected Semantic Entities 

Purpose: To first-degree connect semantic entities of semantic entities (Business Terms, Metrics, Analyses) matching a given name. 

Detail	Description
Endpoint	GET /mcp/semantic-exploration/:id
Input	Element id
Output	List of semantic entities with name, type, description, certified status, owners, tags, modified by, created by, queries, dashboards, visuals, usage

Get Connected Data Elements 

Purpose: To first degree connected tables, views, materialized views of tables, views, materialized views matching a given id. 

Detail	Description
Endpoint	GET /mcp/data-exploration/:id
Input	Element id
Output	List of tables, views, materialized views with name, type, description, certified status, owners, tags, modified by, created by, queries, usage, tables, columns

Omni Context History 

Purpose: To retrieve the authenticated user’s past questions, allowing the user to recall previous conversations Contexts. Facilitates contextual continuity and auditing by allowing retrieval of the historical sequence of questions that established the current context.

Detail	Description
Endpoint	GET /mcp/omniAnalytics/userHistory
Input	default value is 1 month OR “ < time interval>, <number of questions>”
Output	List of prompts

Get SQL Queries 

Purpose: To retrieve all past generated SQL queries.

Detail	Description
Endpoint	GET /mcp/queries
Input
Output	List of queries with id, SQL Code, Usage, Last Queried

Get SQL Query’s data objects

Purpose: To retrieve query information with related data objects 

Detail	Description
Endpoint	GET /mcp/queries/:id
Input	Query id
Output	SQL code, Usage, Frequency, Last Queried, Data Objects

Get Accessible data Entities from zones

Purpose: Returns the complete list of unique data elements that are accessible from at least one zone in the BI system. This endpoint aggregates all data elements exposed by the various zones, removes duplicates, and provides a unified view of the accessible data across the entire system 

Detail	Description
Endpoint	GET /mcp/data-entities/accessible-zones
Input
Output	List of tables, views, materialized views with name, type, description, certified status, owners, tags, modified by, created by, queries, usage, tables, columns