Files · Azure AI MCP Server for SMB Business Intelligence
61 (1 binary, 670.4 kB total)attempt 3
README.md·8273 B·markdown
markdown
# Azure AI MCP Server for SMB Business Intelligence
> Deploy a multi-tenant MCP server that lets AI agents query business intelligence dashboards securely, with per-client rate limits and isolated tools.
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI systems with the `@reaatech/*` package family.
[](package.json)
[](LICENSE)
## What This Does
This recipe deploys a multi-tenant MCP server using `@reaatech/mcp-server-engine` on Express 5, with `@reaatech/multi-tenant-mcp-middleware` enforcing per-tenant tool visibility and rate limits, `postgres.js` for tenant-scoped BI queries, Azure AI Foundry as the reasoning provider, and `@reaatech/mcp-server-observability` for OpenTelemetry tracing to Azure Monitor.
## Prerequisites
- Node.js >=22
- pnpm 10
- A running Postgres instance
- A running Redis instance
- An Azure OpenAI resource
## Package Versions
| Package | Version |
|---------|---------|
| `@azure/openai` | 2.0.0 |
| `openai` | 6.42.0 |
| `@modelcontextprotocol/sdk` | 1.29.0 |
| `@reaatech/mcp-server-core` | 1.0.1 |
| `@reaatech/mcp-server-engine` | 1.0.1 |
| `@reaatech/mcp-server-observability` | 1.1.0 |
| `@reaatech/multi-tenant-mcp-middleware` | 0.1.0 |
| `express` | 5.2.1 |
| `ioredis` | 5.11.1 |
| `postgres` | 3.4.9 |
| `zod` | 4.4.3 |
| `next` | 16.2.9 |
| `react` | 19.2.4 |
| `typescript` | 5.9.3 |
| `vitest` | 4.1.8 |
## Quick Start
```bash
cp .env.example .env # Then fill in your credentials
pnpm install
pnpm test # Verify everything works
pnpm dev # Start server on port 8080
```
## Architecture
```
┌──────────────┐ ┌─────────────────────────────────────┐
│ │ │ MCP Transport Layer │
│ AI Agent │───▶│ (Stdio / SSE / Streamable HTTP) │
│ (Claude) │ └─────────────────────────────────────┘
└──────────────┘ │
▼
┌──────────────────────────────────────────────────────────┐
│ Express 5 Server │
│ ┌────────────────────────────────────────────────────┐ │
│ │ Auth Middleware (API Key / Bearer JWT) │ │
│ ├────────────────────────────────────────────────────┤ │
│ │ Rate Limit Middleware (Redis sliding window) │ │
│ ├────────────────────────────────────────────────────┤ │
│ │ Multi-Tenant Middleware │ │
│ │ • JWT tenant resolution (x-tenant-id) │ │
│ │ • Tool visibility filter (basic vs premium) │ │
│ ├────────────────────────────────────────────────────┤ │
│ │ BI Tool Handlers │ │
│ │ • listSales / getRevenueSummary │ │
│ │ • getTopProducts / getUserAnalytics │ │
│ │ • Tenant-scoped Postgres queries │ │
│ └────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ MCP Response (SDK-formatted) │
└──────────────────────────────────────────────────────────┘
Observability (@reaatech/mcp-server-observability)
OpenTelemetry ──▶ Azure Monitor (traces/metrics/logs)
```
## MCP Tools
| Tool | Description | Parameters |
|---------------------|----------------------------------------------------|-----------------------------------------------|
| `listSales` | List sales records for the current tenant | `tenantId`, `limit?`, `offset?` |
| `getRevenueSummary` | Revenue aggregated by period for the tenant | `tenantId`, `period?` (month/quarter/year) |
| `getTopProducts` | Top N products by revenue for the tenant | `tenantId`, `topN?`, `since?` |
| `getUserAnalytics` | User signup analytics by period for the tenant | `tenantId`, `period?` (month/quarter/year) |
## Multi-Tenancy
- **JWT header**: `x-tenant-id` header for tenant resolution
- **Tool visibility**: Per-tenant policies (`basic` vs `premium` tiers)
- **Rate limiting**: Redis-backed sliding-window rate limiter at 100 RPM per tenant
## Environment Variables
| Variable | Type | Description |
|---------------------------------|----------|------------------------------------------------|
| `NODE_ENV` | string | Environment (development, production, test) |
| `PORT` | number | Server port (default 8080) |
| `DATABASE_URL` | string | Postgres connection string |
| `REDIS_URL` | string | Redis connection string |
| `AZURE_OPENAI_ENDPOINT` | string | Azure OpenAI endpoint URL |
| `AZURE_OPENAI_API_KEY` | string | Azure OpenAI API key |
| `AZURE_OPENAI_DEPLOYMENT` | string | Azure OpenAI deployment name |
| `AZURE_OPENAI_API_VERSION` | string | Azure OpenAI API version (default 2024-10-21) |
| `CORS_ORIGIN` | string | CORS allowed origin(s) |
| `API_KEY` | string | Shared secret for MCP auth |
| `AUTH_MODE` | string | Authentication mode (api-key or bearer) |
| `RATE_LIMIT_RPM` | number | Rate limit per minute per tenant |
| `LOG_LEVEL` | string | Log level (debug, info, warn, error) |
| `OTEL_EXPORTER_OTLP_ENDPOINT` | string | OTLP collector URL for OpenTelemetry |
| `OTEL_SERVICE_NAME` | string | Service name for OpenTelemetry |
## Testing
```bash
pnpm test
```
Runs vitest with coverage. Mocks all external dependencies. Targets >=90% coverage on runtime code.
## Project layout
```
app/ Next.js App Router pages + API routes
src/ services, lib, adapters
lib/db.ts Postgres client
lib/redis.ts Redis client
lib/azure-ai.ts Azure OpenAI configuration
middleware/tenant.ts Multi-tenant middleware
tools/bi.ts BI MCP tools
server.ts Server bootstrap
index.ts Entry point
tests/ vitest suite (mirrors src/)
packages/ API references for every dependency (read these first)
```
## License
MIT — see [LICENSE](./LICENSE).