Semantic BI MCP

Model Context Protocol (MCP) server that gives AI assistants a safe, correct data-analyst capability over business metrics - without raw SQL improvisation.

Talk to your data in plain English. Get answers that are always correct and can never break anything.

What makes this different

Most data MCPs expose a raw SQL runner and let the model improvise. That miscounts, mis-joins, ignores soft-deletes, and can mutate or leak data.

This project does the opposite: a semantic layer. Every business metric is defined once as vetted SQL in lib/metrics.ts and exposed as an MCP tool. The model assembles answers from correct building blocks. Guardrails (read-only, caps, PII masking, audit log) are first-class features.

Related MCP server: MCP SQL Server

Architecture

One Next.js app, four layers:

Tech stack

• Next.js 15 (App Router), TypeScript, Tailwind CSS 4

• MCP: mcp-handler + @modelcontextprotocol/sdk@^1.26

• Data: sql.js (WASM SQLite, serverless-safe)

• Agent: @langchain/mcp-adapters, @langchain/langgraph, @langchain/openai

• Deploy: Vercel Pro + Fluid compute

Quick start

See INSTALLATION.md for full setup including environment variables.

npm install
cp .env.example .env.local   # fill in keys
npm run dev

• Chat UI: http://localhost:3000

• MCP endpoint: http://localhost:3000/api/mcp

• MCP Inspector: npx @modelcontextprotocol/inspector

MCP capabilities

Tools (11)

Resources (3)

• dataset://schema - table/view definitions

• semantic-layer://catalog - metric catalog JSON

• dataset://stats - dataset overview

Prompts (3)

• executive-summary - monthly SaaS health summary

• mrr-trend-analysis - compare two months

• churn-investigation - structured churn analysis

Security

See SECURITY.md for the full security audit and status.

Project docs

• INSTALLATION.md - setup and env var guide

• SECURITY.md - security posture and audit

License

Neural LB - portfolio / demo use. Dataset is fictional (Northwind SaaS).