Illuminate MCP Server

Local-first MCP server for querying Anthology Illuminate data in Snowflake, with interactive MCP App dashboards that render directly in the conversation.

Features

• Local stdio transport (Content-Length framed, with ndjson fallback)

• MCP Apps — interactive UI components (dashboards, schema explorer, insights feed, SQL viewer) rendered inline in the conversation via the MCP Apps extension

• 9 CDM domains with builtin metadata catalog, extensible via Snowflake introspection

• Optional LEARN schema support (Blackboard Open Database Schema, Premium tier)

• Read-only SQL policy with schema/table allowlists

• Metadata-grounded SQL planning without server-side LLM credentials

• Query optimizer — automatic term scoping, smart LIMIT inference, EXPLAIN pre-check for large scans

• Insights engine — automated diagnostic queries with anomaly detection, term-scoped to current academic period

• Adaptive response payloads: summary text, table data, chart hints

• Budget tracking with configurable credit thresholds

• Async query execution for long-running jobs

• Paginated results — dashboard fetches additional rows on scroll via get_result_page

• Planner feedback loop with optional persistence

Related MCP server: MCP Snowflake Server NSP

MCP Apps

This server uses the MCP Apps extension to render interactive UI components directly inside the AI conversation. MCP Apps are supported by Claude Desktop, ChatGPT, VS Code Copilot, and other MCP-compatible hosts.

Available Apps

How MCP Apps work

1. Tools declare a _meta.ui.resourceUri pointing to a ui:// HTML resource

2. When the host calls a tool with UI binding, it fetches the HTML and renders it in a sandboxed iframe

3. The app receives tool results via ontoolresult and renders the interactive UI

4. The app can call server tools via callServerTool (e.g., paginated data fetch, entity details)

5. The app can send messages to the chat via sendMessage (e.g., drill-down follow-ups)

6. The app can update model context via updateModelContext for background context

Tool selection rules

The server instructs the LLM to use tools in this order:

1. run_query — default for ALL data gathering and analysis. Returns data to the LLM with no UI rendered.

2. display_query — ONLY after analysis is complete and the user should see an interactive dashboard. Re-runs the same SQL (Snowflake caches results, so re-execution is instant and free).

3. display_sql — when the user asks to see or review a generated SQL query.

4. discover_insights — when the user asks for anomalies, red flags, or what they should look at.

5. open_schema_explorer — ONLY when the user explicitly asks to browse the schema.

Supported domains

Quick start

macOS / Linux

Requirements: Python 3.12+ (pyenv recommended)

# 1. Clone and enter the repo
cd illuminate-mcp

# 2. Set Python version
pyenv local 3.12.12

# 3. Install package
python -m pip install -e .

# 4. Install Snowflake connector (required for live queries)
python -m pip install -r requirements-snowflake.txt

# 5. Configure environment
cp .env.example .env
# Edit .env with your Snowflake credentials and desired settings

# 6. Run tests
PYTHONPATH=src python -m unittest discover -s tests -v

# 7. Start the server
illuminate-mcp

Windows

Requirements: Python 3.12+ from python.org or via winget install Python.Python.3.12

# 1. Clone and enter the repo
cd illuminate-mcp

# 2. Install package
python -m pip install -e .

# 3. Install Snowflake connector (required for live queries)
python -m pip install -r requirements-snowflake.txt

# 4. Configure environment
copy .env.example .env
# Edit .env with your Snowflake credentials and desired settings

# 5. Run tests
set PYTHONPATH=src
python -m unittest discover -s tests -v

# 6. Start the server
illuminate-mcp

Claude Code / Claude Desktop configuration

Add the server to your MCP client config. The config file location depends on your platform:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "illuminate-mcp": {
      "command": "illuminate-mcp",
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account",
        "SNOWFLAKE_USER": "your-user",
        "SNOWFLAKE_PASSWORD": "your-password",
        "SNOWFLAKE_ROLE": "your-role",
        "SNOWFLAKE_WAREHOUSE": "your-warehouse",
        "SNOWFLAKE_DATABASE": "your-database",
        "ENABLE_QUERY_EXECUTION": "true",
        "ENABLE_METADATA_INTROSPECTION": "true"
      }
    }
  }
}

Note: Env vars in the client config take precedence over .env. You can put credentials in the client config and keep everything else in .env — the server merges both, with client config winning on conflicts.

Windows note: If illuminate-mcp is not found in PATH after pip install, use the full path to the script: "command": "C:\\Users\\<you>\\AppData\\Local\\Programs\\Python\\Python312\\Scripts\\illuminate-mcp.exe"

The server automatically loads .env from the project directory on startup — no manual env sourcing needed.

Configuration

All configuration is via environment variables in .env. See .env.example for the full template with comments.

Snowflake credentials

Required when ENABLE_QUERY_EXECUTION=true or ENABLE_METADATA_INTROSPECTION=true:

• SNOWFLAKE_ACCOUNT - Account identifier (URL prefix is stripped automatically)

• SNOWFLAKE_USER - Service account username

• SNOWFLAKE_PASSWORD - Service account password

• SNOWFLAKE_ROLE - Query execution role

• SNOWFLAKE_WAREHOUSE - Compute warehouse

• SNOWFLAKE_DATABASE - Target database

Domain and schema allowlists

• ALLOWED_DOMAINS - Comma-separated CDM domains to expose (default: CDM_LMS,CDM_TLM,CDM_ALY)

• ALLOWED_SCHEMAS - Comma-separated schemas for policy enforcement (should match domains)

• ALLOWED_TABLES - Optional table-level allowlist (empty = all tables in allowed schemas)

Domains with no tables in Snowflake are automatically excluded when metadata introspection is enabled.

LEARN schema (opt-in)

The LEARN schema provides access to 191+ raw Blackboard Learn source tables. It requires Illuminate Premium tier.

ENABLE_LEARN_SCHEMA=true

When enabled, LEARN is automatically added to ALLOWED_DOMAINS and ALLOWED_SCHEMAS.

Feature flags

Runtime limits

Budget governance

Output shaping

MCP tools

Query tools

Schema tools

Planning tools

Analytics tools

Governance tools

MCP resources

Query optimizer

The query optimizer runs automatically before every run_query and display_query execution:

1. Term scoping — if the query touches a table with a temporal column and the question doesn't ask for historical/trend data, a current-term date filter is injected automatically (~120 days)

2. Smart LIMIT — non-aggregate queries without a LIMIT get one inferred from the question intent (25 for previews, 200 for lists, 500 for investigations, 5000 for "all")

3. EXPLAIN pre-check — estimates scan size before execution and warns if >10M rows or >500 partitions

4. SELECT * hint — flags queries using SELECT * for potential column reduction

5. Safety wrapper — the optimizer never blocks execution; if it fails, the original SQL runs unchanged

Applied optimizations are returned in optimizations_applied and warnings in optimization_warnings in the query response.

Insights engine

discover_insights runs 10 diagnostic queries across configured CDM domains:

• CDM_LMS: Enrollment trend, zero-activity courses, low normalized scores, attempt completion, low instructor activity

• CDM_TLM: Telemetry event volume

• CDM_ALY: Course accessibility score distribution, stale content scores

• CDM_SIS: Enrollment trend, student status distribution

Queries are scoped to the current academic term (resolved from CDM_LMS.TERM). Findings are severity-ranked (critical/warning/info/ok) with threshold-based anomaly detection. Each insight card includes:

• Severity badge and domain tag

• Metric display with change percentage

• Info icon with explanation of what the check measures

• SQL icon showing the exact query that ran

• "Dig into this" button that sends a follow-up query via sendMessage

Errors from missing schemas are classified as "skipped" (not "failed") for clean UX.

MCP prompts

Query planning workflow

1. Use plan_query to get multiple ranked SQL candidates

2. generate_sql returns the top recommended candidate

3. Execute with run_query (sync) or start_query (async)

4. If no data returned, check no_data_diagnostics.refinement_candidates in the response

5. Use refine_sql to get retry candidates for failed queries

6. Use get_planner_feedback to inspect execution history influencing rankings

MCP compatibility

• Supports MCP Apps extension (SEP-1865, spec 2026-01-26) for inline interactive UI

• Supports prompts/list and prompts/get for clients that resolve prompt payloads explicitly

• Tool execution failures are returned as tools/call results with isError=true

• Supports Content-Length framed stdio (default) and ndjson mode (MCP_STDIO_MODE=ndjson)

Run tests

PYTHONPATH=src python -m unittest discover -s tests -v

Operations

See OPERATOR_RUNBOOK.md for startup checks, troubleshooting, and incident handling.

Architecture

See DESIGN.md for design decisions and system architecture.