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.

Architecture

One Next.js app, four layers:

Layer	Path	Purpose
MCP server	app/api/[transport]/route.ts	Tools, resources, prompts at /api/mcp
Semantic layer	lib/	sql.js dataset, metrics, guards, audit, auth
LangChain agent	app/api/chat/route.ts	gpt-4o-mini -> MCP over HTTP
Chat UI	app/page.tsx + components/	Live tool-call visualization

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)

Tool	Description
get_mrr	Monthly Recurring Revenue
get_arr	Annual Recurring Revenue
get_churn_rate	Subscription churn %
get_active_subscriptions	Active/trialing count by tier
get_new_customers	New customer acquisitions
get_revenue_by_plan	Paid revenue by plan
get_customer_count	Active customer count
get_net_revenue_retention	NRR between two months
safe_query	Read-only SELECT on whitelisted views
list_metrics	Metric catalog
get_audit_log	Recent tool invocations

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).