Overview

Azure ADX MCP Server for Data Explorer Queries is a lightweight Model Context Protocol (MCP) server that exposes Azure Data Explorer (ADX / Kusto) as a programmable backend for tools and LLM integrations. It accepts MCP-style requests to run queries against ADX clusters, returns structured results, and can be used to accelerate query workflows, generate visualizations, and centralize cluster access for applications or agents.

This server is useful when you need a controlled API layer over ADX that supports authenticated access (service principal or managed identity), query batching and caching, result formatting (JSON/CSV/table), and simple operational endpoints (health, schema). It’s designed for developers who want to integrate ADX query capabilities into tools, dashboards, or agent frameworks without exposing raw cluster credentials or embedding Kusto clients directly in every consumer.

Features

Exposes ADX query execution over HTTP with MCP-style request/response patterns
Authenticates to ADX using Azure AD service principals or managed identities
Returns results in multiple formats (JSON, CSV, tabular)
Basic caching and query parameterization to accelerate repeated queries
Endpoints for cluster metadata and database schema discovery
Health and metrics endpoints for monitoring and orchestration
Docker-ready for easy deployment to cloud or on-prem environments

Installation / Configuration

Prerequisites:

Node.js (>= 16) or Docker
An Azure AD service principal with access to the target ADX cluster (or use managed identity from the hosting environment)

Clone and run locally (Node.js):

git clone https://github.com/pab1it0/adx-mcp-server.git
cd adx-mcp-server
npm install
# create .env as shown below
npm run build
npm start

Build and run with Docker:

# from repository root
docker build -t adx-mcp-server:latest .
docker run -e PORT=3000 \
  -e AZURE_TENANT_ID=<tenant> \
  -e AZURE_CLIENT_ID=<client-id> \
  -e AZURE_CLIENT_SECRET=<client-secret> \
  -e ADX_CLUSTER_URI="https://<cluster>.kusto.windows.net" \
  -e ADX_DATABASE="<database>" \
  -p 3000:3000 \
  adx-mcp-server:latest

Example .env file:

PORT=3000
AZURE_TENANT_ID=your-tenant-id
AZURE_CLIENT_ID=your-client-id
AZURE_CLIENT_SECRET=your-client-secret
ADX_CLUSTER_URI=https://yourcluster.kusto.windows.net
ADX_DATABASE=your_database_name
CACHE_TTL=60
LOG_LEVEL=info

Authentication notes:

For production, prefer managed identity when running in Azure (App Service, AKS, VM) to avoid managing secrets.
When using a service principal, ensure it has Data Reader (or appropriate) permissions on the ADX database.

Available Resources

The server exposes a small set of HTTP endpoints useful for automation and integration. Example endpoints:

Endpoint	Method	Description
/mcp/query	POST	Execute a parameterized ADX query and return results (JSON/CSV)
/mcp/schema	GET	Return database schema (tables, columns) for discovery
/health	GET	Liveness and readiness checks
/metrics	GET	Basic metrics (requests, errors, cache hits)
/mcp/metadata	GET	Server metadata and supported response formats

Example request to run a query:

curl -X POST http://localhost:3000/mcp/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "MyTable | where Timestamp >= ago(1d) | summarize count() by Category",
    "format": "json",
    "params": {}
  }'

Sample response (JSON):

{
  "status": "ok",
  "data": [
    { "Category": "A", "count_": 123 },
    { "Category": "B", "count_": 45 }
  ],
  "meta": { "rows": 2, "queryTimeMs": 120 }
}

Use Cases

Query acceleration for analytics UIs: Host the MCP server next to ADX and let dashboards fetch preformatted JSON/CSV, centralizing caching and access control so client apps can be lightweight.
LLM/agent integrations: Use the server as a trusted tool backend for agents that need to run ADX queries. The MCP contract helps agents request queries, receive structured results, and avoid exposing credentials directly.
Operational tooling: Build scripts and automation that query ADX for cluster diagnostics, ingestion status, or telemetry; the server can provide schema discovery and standardized outputs for downstream processing.
Multi-tenant access control: Serve queries from multiple applications or teams through one controlled endpoint, apply rate limits or audit logs, and rotate Azure credentials centrally.

Concrete example — visualize recent errors:

Call /mcp/schema to discover the logs table and timestamp column.
POST to /mcp/query with a parameterized query that aggregates error counts by service over the last 2 hours.
Feed the JSON result into a charting component (client-side or server-side) to render a time-series chart.

Getting Help & Contributing

Source and issues: https://github.com/pab1it0/adx-mcp-server
When opening issues, include: ADX cluster URI (or masked), .env sample (no secrets), and server logs.
Contributions: PRs for additional endpoints (e.g., query explain, async job API, config-driven caching) and authentication methods are welcome.

This MCP server provides a pragmatic bridge between ADX and developer-oriented tooling, making it easier to query, visualize, and manage Data Explorer workloads from centralized services or agent frameworks.