MCP Dashboard

A minimal dashboard for MCP services (local backend + server + tools).

Features

• Local mock backend and API client utilities
• Services for analytics, wallet, transactions, vendors, and more

Prerequisites

• Node.js (16+)
• npm or yarn

Install

npm install

Run (development)

npm run dev

Build

npm run build

Project structure (key files)

• src/: application source
  • src/server.ts - main server
  • src/chatServer.ts - chat server
  • src/localBackend.ts - local backend
• api/axios.ts - axios client
• services/ - business logic services
• tools/ - utility scripts (analytics, dashboard, etc.)

Notes

• See package.json for available npm scripts.
• This README is a starting point — expand sections as needed.

FinOps AI Copilot MCP Server

A production-quality Model Context Protocol (MCP) server that acts as a secure, read-only AI gateway for fintech operations dashboards. It allows LLMs (such as Cursor, Claude Desktop, or OpenAI-compatible engines) to inspect transactions, vendor performance, wallet balances, and analytics via secure REST APIs instead of exposing the database directly.

Project Overview

FinOps AI Copilot enables natural language query resolution for operational and financial dashboards. By exposing standardized tools through the Model Context Protocol, the AI assistant can query real-time data securely.

Architecture

graph TD
    User([User Query]) --> Client[Claude Desktop / Cursor / AI Client]
    Client -->|JSON-RPC via stdio| Server[FinOps MCP Server]
    Server -->|Zod Validation| Services[Service Layer]
    Services -->|Axios REST Calls| Backend[Dashboard Backend REST API]
    Backend --> DB[(MongoDB Database)]

Security Design

1. Read-Only Enforcement: The MCP server only exposes query tools (get*, find*, compare*, summary). No state-changing endpoints are integrated.
2. Gateway Pattern: The AI client never directly talks to MongoDB or runs raw queries. All requests pass through the gateway and are validated against strict Zod schemas.
3. Data Sanitization: Secrets, customer sensitive credentials, and database keys are never exposed in tool definitions.
4. Environment Isolation: API endpoints and credentials are loaded dynamically from environment variables.

---

Installation

Prerequisites

• Node.js (v18 or higher)
• npm or yarn

Setup

1. Clone or navigate to the workspace directory:

   cd "/Users/apple/Desktop/mcp dasboard"
   

2. Install dependencies:

   npm install
   

3. Configure Environment Variables: Copy .env.example to .env and fill in the details:

   cp .env.example .env
   

---

Environment Variables

Variable	Description	Default
PORT	Local port for optional server operations	3000
BACKEND_API_URL	Base URL of the existing REST API	http://localhost:4000/api
BACKEND_API_KEY	Bearer Token / API key for REST endpoints	mock-api-key-12345
LARGE_TRANSACTION_THRESHOLD	Threshold to filter large payments	50000

---

Available Tools

The MCP server registers the following operational tools:

1. Dashboard

• getDashboardMetrics: High-level business overview (Total processed volume, count, success rate, failed amount, pending transaction count, wallet balance).

2. Transactions

• findTransactionById: Search transaction details by transaction ID.
• findTransactions: Search for transactions using filters like status, vendor, merchant, amount range, and dates.
• failedTransactions: Retrieve failed transaction list (supports pagination).
• pendingTransactions: Retrieve pending payout/settlement list.
• largeTransactions: Retrieve payments exceeding the threshold.
• retryTransactions: Retrieve payments that have been retried multiple times.

3. Vendors

• vendorPerformance: Return success/failure rates, average response times, and volumes for a specific vendor.
• topVendor: Get vendor with the highest success rate.
• worstVendor: Get vendor with the highest failure rate.
• vendorComparison: Side-by-side comparison of two vendors.

4. Wallet

• walletBalance: Current wallet balance across channels.
• walletHistory: Log of credit/debit adjustments and balance history.

5. Analytics & AI Summary

• todayVsYesterday: Daily comparison of transactions count, amount, and success rates.
• weeklyAnalytics: Last 7 days metrics.
• monthlyAnalytics: Current month summaries.
• peakHour: Identifies busiest transaction hour.
• merchantAnalytics: Top merchants by volume and transaction count.
• dailySummary: AI-structured daily business performance summary with recommendation.

---

Claude Desktop Configuration

To link this server with your Claude Desktop client, append the following block to your local configuration file:

File Paths

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Snippet

{
  "mcpServers": {
    "finops-ai-copilot": {
      "command": "node",
      "args": [
        "/Users/apple/Desktop/mcp dasboard/node_modules/tsx/dist/cli.js",
        "/Users/apple/Desktop/mcp dasboard/src/server.ts"
      ],
      "env": {
        "BACKEND_API_URL": "http://localhost:4000/api",
        "BACKEND_API_KEY": "mock-api-key-12345",
        "LARGE_TRANSACTION_THRESHOLD": "50000"
      }
    }
  }
}

---

Testing locally

To run the mock backend and query the services locally:

1. Start the mock backend REST API (runs on port 4000):

   npx tsx scratch/mock_backend.ts
   

2. Run the integration test client:

   npx tsx scratch/test_client.ts
   

3. Type check the server code:

   npm run build
   

---

Future Roadmap

• Anomaly Detection: Flags sudden drops in success rates.
• Root Cause Analysis: Diagnoses why transactions fail (e.g., bank downtime vs. card failure).
• Fraud Detection: Identifies velocity spikes or suspicious repeated low-value transactions.
• Vendor Recommendation: Dynamic routing recommendations to route traffic away from degrading vendors automatically.
• Scheduled Reports: Automatic generation and distribution of daily/weekly reports via email or Slack.
• Role-Based Access Control (RBAC): Fine-grained user/client permissions for different categories of financial metrics.