Analytics AI Integration

This guide covers the technical implementation of the Agentic AI analytics feature using Model Context Protocol (MCP) and the Cube.js semantic layer.

Monorepo Available

All AI analytics components are consolidated in the ctms-data-pipeline-ai-analytics monorepo for easier development and deployment.

---

Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  AI Chat UI     │────▶│  MCP Agent      │────▶│  Cube.js        │
│  (React)        │     │  (FastAPI)      │     │  Semantic Layer │
│  :3000          │     │  :8006          │     │  :4000          │
└─────────────────┘     └─────────────────┘     └─────────────────┘
        │                       │                       │
        │                       ▼                       │
        │               ┌─────────────────┐             │
        │               │  OpenAI LLM     │             │
        │               │  (gpt-4o-mini)  │             │
        │               └─────────────────┘             │
        │                       │                       │
        └───────────────────────┴───────────────────────┘
                        Response

---

Components

MCP Agent Service

Located in ctms-mcp-server/, the agent bridges the chat UI to Cube.js:

Component	Purpose
index.js	MCP server with tool definitions
agent_service_mcp_client.py	FastAPI REST bridge
configs/	Client configurations

Cube.js Semantic Layer

Located in ctms-cube/:

Component	Purpose
model/cubes/	Cube definitions (measures, dimensions)
model/views/	Pre-joined views for common queries
cube.js	Cube.js configuration

---

MCP Tools

The agent exposes these tools to the AI:

Tool	Description
cube_get_meta	Get metadata about cubes, measures, dimensions
cube_query	Execute queries against semantic layer
cube_get_sql	Get generated SQL for queries
cube_list_cubes	List all available cubes
cube_describe_cube	Describe a specific cube
cube_clinical_kpis	Get pre-defined clinical KPIs

---

## Available Cubes for AI

The AI can query these cubes:

| Cube | Key Measures | Key Dimensions |
|------|--------------|----------------|
| `Enrollments` | subjectCount, screenFailureCount | studyId, siteId, status |
| `Studies` | count, avgDurationDays | studyPhase, studyStatus |
| `VitalSigns` | avgValue, measurementCount | testCode, testName |
| `AdverseEvents` | count, saeCount | severity, bodySystem |
| `Visits` | visitCount, completionRate | visitStatus, visitType |
| `Sites` | count, activeSites | countryName, siteStatus |

---

## Enabling AI for Users

### Role-Based Access

AI access is controlled in the frontend:

```tsx
// Only show AI panel for Platform Administrators
const { roles } = useAuth();
const showAI = roles.includes(ROLES.ADMIN);

return (
  <>
    {showAI && <AnalyticsAIPanel />}
  </>
);

Session Initialization

AI session requires page refresh to initialize MCP connection:

useEffect(() => {
  if (isAdmin) {
    initializeMCPConnection();
  }
}, [isAdmin]);

---

Query Flow

1. User Input — Natural language question
2. LLM Processing — Claude interprets intent
3. Tool Selection — AI selects appropriate MCP tool
4. Cube Query — MCP server queries Cube.js
5. Response Formatting — AI formats results
6. UI Rendering — React renders response

// Simplified flow
const handleUserQuery = async (question: string) => {
  const response = await mcpClient.chat({
    message: question,
    tools: availableTools,
  });
  
  setMessages(prev => [...prev, response]);
};

---

Adding New AI Capabilities

1. Add Cube Measure

In ctms-semantic-cube/model/cubes/:

cube(`NewMetric`, {
  sql: `SELECT * FROM fact_new_metric`,
  
  measures: {
    count: {
      type: `count`,
    },
    avgValue: {
      type: `avg`,
      sql: `value`,
    },
  },
});

2. Expose via MCP

In MCP server configuration, the new cube is automatically available.

3. Test with AI

User: "Show me the new metric count"
AI: Queries NewMetric.count via MCP

---

Running Locally

Option A: Monorepo (Recommended)

# Clone the monorepo
git clone git@github.com:zynomilabs/ctms-data-pipeline-ai-analytics.git
cd ctms-data-pipeline-ai-analytics

# Set up environment
cp .env.production .env

# Start the full stack
make stack

This starts:

• Cube.js at http://localhost:4000
• MCP Agent at http://localhost:8006

Option B: Standalone Repositories

Start MCP Server:

cd ctms-mcp-server
pip install -r requirements.txt
make run

Start Cube.js:

cd ctms-semantic-cube
npm install
npm run dev

Start Web App

cd hb-life-science-web
bun run dev

Test Endpoints

# Verify MCP Agent health
curl http://localhost:8006/health

# Test Cube.js
curl -s "http://localhost:4000/cubejs-api/v1/load" \
  -H "Content-Type: application/json" \
  -d '{"query": {"measures": ["Studies.count"]}}'

---

Debugging

Monorepo Logs

cd ctms-data-pipeline-ai-analytics

# View Cube.js logs
make cube-log

# View MCP Agent logs
make mcp-agent-log

# Check all ports
make ports-check

Standalone Logs

# MCP Server logs
cd ctms-mcp-server && tail -f logs/mcp_server.log

# Cube.js logs
cd ctms-semantic-cube && tail -f logs/cube_*.log

Browser Console

Check for MCP connection errors:

• MCP connection failed
• Tool execution error
• Cube query timeout

---

Security Considerations

Aspect	Implementation
Authentication	AI only accessible to authenticated admins
Authorization	MCP respects user role permissions
Query Limits	Cube.js enforces row limits
Rate Limiting	MCP server rate limits requests
Audit Logging	All AI queries are logged