@mithung/vunet-mcp-server

Model Context Protocol (MCP) Server for Vunet vuSmartMaps - A multi-tenant observability platform integration.

Query metrics, traces, logs, and data models from your Vunet tenants using natural language through AI assistants like Claude, GitHub Copilot, or any MCP-compatible client.

Latest Version: 2.2.0 - Added vunet_fetch_datamodels tool for live data model discovery from the VuNet API.

🚀 Features

• ✅ Multi-Tenant Support - Connect to multiple Vunet tenants simultaneously

• 🔐 Secure Authentication - Session-based auth with automatic token refresh

• 📊 Comprehensive Data Access - Query 600+ data models including:

  • Journey Metrics (IBMB, UPI, CBS, FRM)

  • Application traces and exceptions

  • Infrastructure metrics (CPU, Memory, Disk)

  • Kubernetes metrics

  • Alert data and RCA metrics

• ⚡ Flexible Querying - Support for:

  • Relative time ranges (5m, 15m, 1h, 2h, 1d, 1w, 1M)

  • Absolute time ranges (epoch timestamps)

  • Dynamic filters and field selection

• 🔄 Auto Session Management - Handles login, token refresh, and logout

• 🌐 Proxy Support - Works with Traefik and other reverse proxies

📦 Installation

Using npx (Recommended - No Installation Required)

npx @mithung/vunet-mcp-server

Global Installation

npm install -g @mithung/vunet-mcp-server

Local Installation

npm install @mithung/vunet-mcp-server

🛠️ Configuration

VS Code / GitHub Copilot Setup

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "vunet": {
      "command": "npx",
      "args": ["@mithung/vunet-mcp-server"],
      "env": {
        "VUNET_TENANT_URL": "https://your-tenant.vunetsystems.com",
        "VUNET_USERNAME": "your-username",
        "VUNET_PASSWORD": "your-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "true"
      }
    }
  }
}

Multiple Tenants

{
  "servers": {
    "vunet-prod": {
      "command": "npx",
      "args": ["@mithung/vunet-mcp-server"],
      "env": {
        "VUNET_TENANT_URL": "https://prod.vunetsystems.com",
        "VUNET_USERNAME": "prod-user",
        "VUNET_PASSWORD": "prod-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "true"
      }
    },
    "vunet-uat": {
      "command": "npx",
      "args": ["@mithung/vunet-mcp-server"],
      "env": {
        "VUNET_TENANT_URL": "https://uat.vunetsystems.com",
        "VUNET_USERNAME": "uat-user",
        "VUNET_PASSWORD": "uat-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "false"
      }
    }
  }
}

Running from Source

If you've cloned the repository:

{
  "servers": {
    "vunet": {
      "command": "node",
      "args": ["c:\\path\\to\\vunet-mcp-server\\index.js"],
      "env": {
        "VUNET_TENANT_URL": "https://your-tenant.vunetsystems.com",
        "VUNET_USERNAME": "your-username",
        "VUNET_PASSWORD": "your-password",
        "VUNET_BU_ID": "1",
        "VUNET_VERIFY_SSL": "false"
      }
    }
  }
}

📊 Available MCP Tools

1. vunet_get_status

Check the current connection status and tenant information.

Example: "Check if Vunet connection is working"

2. vunet_list_data_models

List common Vunet data models organised by category (APM, Infrastructure, Database, Network, etc.).

Parameters:

Example: "List all available Vunet data models"
Example: "Show me infrastructure data models in Vunet"

3. vunet_fetch_datamodels

Fetch the actual live DataModels (signals) configured in this VuNet tenant via /api/vuaccel/datamodel/. Returns real signal names, types (Metric/Event/Log), data sources, and column details. Use this to discover what data is available before querying with vunet_query_metric.

Parameters:

Example: "Fetch all live data models from VuNet"
Example: "Find data models related to UPI in VuNet"
Example: "List all Event type data models"

4. vunet_query_metric

Query a specific metric with time range and filters.

Parameters:

💬 Usage Examples

Check Connection Status

"Is the Vunet MCP server connected?"

Discover Live Data Models

"Fetch all available data models from VuNet"
"Show me all Metric type data models"
"Find data models related to UPI payments"
"Search for CPU-related data models in VuNet"

List Categorised Data Models

"What data models are available in Vunet?"
"Show me infrastructure data models"
"List all APM data models"

Query Journey Metrics

"Show me IBMB Journey Metrics for the last 2 hours"
"Get UPI Volume data for the last 1 hour"
"Query CBS TAT metrics for the last 30 minutes"

Query Alerts

"Get all critical alerts from the last 1 hour"
"Show warning alerts with group values for the last 15 minutes"

Query with Filters

"Query IBMB Journey Metrics where name equals CBS for the last 30 minutes"
"Get Linux CPU Utilization filtered by hostname for the last 2 hours"

Infrastructure Monitoring

"Show CPU utilization for IBMB servers in the last hour"
"Get memory utilization for CBS servers in the last 2 hours"
"Show MSSQL blocking sessions for the last 30 minutes"

RCA Analysis

"Get Technical Decline data for IBMB in the last 2 hours"
"Show RCA root cause data for the last 1 hour"
"Query RCA lead indicators for the last 4 hours"

Time Comparison

"Compare UPI Volume for the last 1 hour vs same time yesterday"
"Show IBMB TAT with 1-day comparison"

🔧 Environment Variables

📈 Common Data Models

Journey Metrics

• IBMB Journey Metrics - Internet/Mobile Banking metrics

• UPI Journey Metrics - UPI payment metrics

• CBS Journey Metrics - Core Banking metrics

• FRM Journey Metrics - Fraud Risk Management

RCA (Root Cause Analysis)

• RCA IBMB TD - Technical Decline breakdown

• RCA CPU Utilization IBMB - Server CPU metrics

• RCA Memory Utilization IBMB - Server memory metrics

• Linux Disk Utilization IBMB - Disk usage

Alerts

• Alert data - All active alerts with severity

• IBMB Exceptions - Application exceptions

Infrastructure

• Kubernetes Pod Metrics

• Linux Host Metrics

• Network Metrics

🔥 Troubleshooting

Authentication Failed (401)

Error: www-authenticate: Basic realm="traefik"

Solution: Your environment may have a Traefik proxy. The MCP server v2.1.0+ handles this automatically.

Session Expired

The server automatically refreshes sessions. If issues persist, restart the MCP server.

SSL Certificate Errors

Set VUNET_VERIFY_SSL to false for self-signed certificates:

"VUNET_VERIFY_SSL": "false"

Data Model Not Found

Use vunet_list_data_models to see available metrics. Names are case-sensitive.

🚀 Quick Start Commands

# Install globally
npm install -g @mithung/vunet-mcp-server

# Or run directly with npx
npx @mithung/vunet-mcp-server

# Check installed version
npm list -g @mithung/vunet-mcp-server

🎯 Real-World Use Cases

The following use cases demonstrate how the VuNet MCP Server enables GitHub Copilot to autonomously investigate incidents, correlate telemetry data, and produce structured Root Cause Analysis — matching and often accelerating what an experienced SRE would find manually through the VuNet UI.

Use Case 1: CBS Oracle DB Failure Causing IBMB Transaction Declines

Scenario: Internet/Mobile Banking (IBMB) transactions were failing at an anomalously high rate. The IBMB journey routes financial transactions through multiple touchpoints: IBMB → FRM (Fraud Risk Management) → CBS (Core Banking System). The task was to identify whether the failure was at the application layer, network layer, or database layer — and pinpoint the exact root cause.

Step 1 — Journey Health Deteriorates: Unstable State Detected

The VuNet IBMB Journey Overview dashboard immediately signals an Unstable State — UEI score dropping to 2.28, Technical Decline spiking to 76.49%, and overall Failure rate at 93.26%. Total Alerts: 8 (6 Critical).

Step 2 — End-to-End Flow Narrows the Failure to CBS

The End-to-End Transaction Journey Flow panel isolates the failure source. While FRM shows 99.2% success, CBS shows 91.3% Technical Decline — pointing directly at CBS as the failing touchpoint.

Step 3 — Individual Failing Transactions Confirm CBS as Failure Point

The Failure Transactions table lists 100 failed FundTransfer transactions. All failures point to Failed At: Oracle DB, Failure Point: CBS, with Response Code 10 (Oracle DB connection issue) and Response Code 11 (Unable to process the request).

Step 4 — Transaction Trace Confirms the CBS → Oracle DB Failure Path

Drilling into a sample transaction (MQAD94455582) via the Transaction Trace view shows the exact span breakdown: IBMB called FRM (success, 4ms), then CBS (failed, 5ms). The Failed At column confirms Oracle DB as the failure node within CBS.

Step 5 — CBS Raw Logs Surface the Exact Exception

The Raw Transaction Log View for the CBS touchpoint exposes the exact error message:

Error while fund transfer. java.sql.SQLRecoverableException: IO Error: The Network Adapter could not establish the connection.

This confirms a TCP-level connection failure between the CBS application server and the Oracle DB listener — not a query timeout, but an immediate connection refusal.

Step 6 — Full Stack Trace Pinpoints the Oracle JDBC Layer

The exception stack trace drills all the way down to the Oracle JDBC driver (T4CConnection.logon → PhysicalConnection.connect → T4CDriverExtension.getConnection), confirming the failure is at TCP connection establishment — not at the SQL execution layer.

The distributed trace view also confirms the POST /cbs/api/v1.0/accounts/fundtransfer span fails in the CBS service.

Step 7 — MCP + GitHub Copilot Produces Automated RCA in Seconds

Using the VuNet MCP Server, GitHub Copilot was given the following prompt directly in VS Code:

"Connect to the ng2 instance and investigate IBMB transaction failures over the last 5 minutes. IBMB transactions flow through to CBS (Core Banking System). Please do the following:

1. Check IBMB Technical Decline (TD%) metrics to quantify the failure rate

2. Query CBS exception logs to identify the specific exception type and count

3. Check CBS TAT (turnaround time) to assess if failures are timeouts or immediate rejects

4. Check the full exception stack trace to pinpoint the root cause layer (network, DB, application)

Based on the data, provide:

• A structured RCA table with metric values vs thresholds and health status

• The root cause with the exact exception trace

• Prioritised recommendations: P1 immediate fix commands, P2 short-term actions, and post-recovery hardening steps

• A one-line executive summary at the end"

Copilot autonomously called multiple MCP tools — querying IBMB TD% metrics, CBS exception logs, CBS TAT data, and stack traces — then produced a structured RCA report:

Root Cause identified by MCP: CBS Oracle DB connectivity failure — Network Adapter cannot establish the TCP connection. The 12.4ms TAT confirmed connections were being immediately refused (not timing out), pointing to Oracle DB listener down, broken network route/firewall, or Oracle DB in restricted mode.

MCP Recommendations (Priority Order):

• P1 (Immediate): SSH into Oracle DB server, check listener status (lsnrctl status), verify connectivity from CBS app server

• P2 (Short-term): Add connection pool health checks, configure JDBC connection timeout alerting

• Post-recovery hardening: Implement Oracle DB availability monitoring, configure automatic failover to standby DB

Key Insight: The MCP Server resolved the RCA in seconds by programmatically querying metrics, logs, and traces in sequence — the same analysis that would take an SRE 15–30 minutes of manual dashboard navigation, matching the exact root cause visible in the VuNet UI.

Use Case 2: CBS Slowness / Timeout Causing IBMB Technical Declines

Scenario: A different class of CBS failure — this time CBS is accepting TCP connections but not responding, causing IBMB's outbound RestTemplate calls to hang until the 1,000ms read timeout fires. Unlike Use Case 1 (where Oracle DB refused connections immediately at ~12ms), here every failed transaction held a thread for a full second before timing out, resulting in cascading thread pool pressure on IBMB. The task was to distinguish this from a connection-refused failure and trace the slowness to the exact CBS internal bottleneck.

Step 1 — Simulation: Injecting CBS Slowness

A controlled simulation (TD-IBMB-Timeout-due-to-CBS-Slowness) was triggered via the VuNet simulation dashboard to reproduce the production scenario — CBS slowness causing IBMB timeouts.

Step 2 — IBMB Journey Enters Unstable State

Within minutes, the IBMB Journey Overview reflects the impact: UEI drops to 9.65 and starts trending down sharply, Slow Transactions spike to 73, Technical Decline climbs to 15.80%, and Response Time (95P) hits 1.04 seconds — the signature of a timeout-class failure (not a fast reject). Total Alerts: 4 Critical.

Step 3 — CBS TAT Spikes to 15 Seconds; TD at CBS Remains Low

The Trends & E2E Transaction Flow panel reveals the critical clue distinguishing this from Use Case 1: CBS shows 96.69% Success (low TD%) but CBS Response Time (95P) = 15.03 seconds — an extreme outlier. Meanwhile IBMB has 73 Slow Transactions and 1.04s P95 TAT. The failure is not CBS rejecting transactions — CBS is accepting them but processing astronomically slowly, causing IBMB to timeout waiting.

Step 4 — Failure Analysis Confirms Response Code 12: SocketTimeout-Read

The Failure Analysis dashboard confirms Response Code 12 (SocketTimeout-Read) across all FundTransfer types (RTGS 35.61%, IMPS 29.55%, NEFT 25.00%) and AccountStatement (7.58%), all with 95P response times of ~1.06 seconds — precisely at IBMB's 1,000ms read timeout. This is unambiguously a socket read timeout, not a connection failure (Code 10/11 from Use Case 1).

Step 5 — Distributed Trace Pinpoints the Slow CBS Span

The Trace Map for a sample failing transaction (caf9c3f4465b72544217e7115f09bb65) exposes the exact span causing the slowness: TransactionRepository.simulateSlowQ... consuming 5,000ms (464.91% of total trace time) — a Spring Data query inside CBS that is hanging. Every downstream span (TransactionService.createDebitTransaction, AccountService.fundTransfer) inherits this 5-second block, while Oracle DB queries themselves are fast (<3ms), ruling out the database as the bottleneck.

Step 6 — MCP + GitHub Copilot RCA: CBS Application Server Hung/Unresponsive

The following prompt was used in GitHub Copilot via the VuNet MCP Server:

"Please connect to ng2 instance. I notice some transactions failing in IBMB over the last 5 mins due to technical issues across. Transactions connect from IBMB to CBS, can you please analyse the logs and search the exception for these failed transactions and come up with a quick RCA and recommendation."

The VuNet MCP Server, queried through GitHub Copilot in VS Code, analysed the CBS exception logs, TAT metrics, and stack trace to produce this root cause determination:

Key observations from the stack trace (identified by MCP):

• Exception originates from SessionInputBufferImpl.streamRead() — CBS sent no HTTP response within the configured socket timeout

• The RestTemplate read timeout is exactly ~1,000ms (all failures cluster at 1,019–1,063ms)

• Both transferFund (line 207) and debit (line 281) operations fail — CBS is not responding at all, not partially

• No ConnectException — CBS is accepting the TCP connection but then going silent (server running but hung/overloaded/deadlocked internally)

Root Cause:

CBS Application Server is HUNG / UNRESPONSIVE
└── Accepts TCP connections from IBMB
└── But never sends HTTP response back
└── IBMB RestTemplate times out after 1,000ms read timeout
    └── java.net.SocketTimeoutException: Read timed out
        └── CbsIntegrationService.transferFund:207
        └── CbsIntegrationService.debit:281
            └── 100% IBMB failure (NEFT 85% TD, RTGS 77% TD, IMPS 79% TD)

This is different from Use Case 1 (Oracle DB connection failure — Code 10, fast fail at 17ms). This incident is CBS accepting connections but not processing requests — indicative of thread pool exhaustion, internal deadlock, long GC pause, or a slow Oracle query consuming all connection pool threads.

Step 7 — MCP Delivers Prioritised Remediation Plan

Key Insight: MCP distinguished this as a timeout-class failure (not a connection-refused failure) by correlating the 1,000ms response time clustering, the SocketTimeoutException stack trace, and the CBS TAT spike — correctly ruling out Oracle DB as the source and pointing to CBS application-layer thread exhaustion. The analysis also explicitly contrasted this with the prior Use Case 1 incident, demonstrating MCP's ability to reason across historical incident patterns.

Use Case 3: FRM Application Layer Slowness Causing IBMB Transaction Delays

Scenario: IBMB transactions were slowing down without a clear spike in Technical Decline or hard failures. The IBMB journey routes through two downstream touchpoints — FRM (Fraud Risk Management) and CBS (Core Banking System). The challenge here is subtler than Use Cases 1 and 2: CBS is healthy, there are no connection errors, and FRM is still successfully approving transactions — but the FRM processing path is running 40–50× slower than normal. MCP was used to identify FRM as the bottleneck with proof points, distinguish it from the earlier CBS outages, and pinpoint the likely internal cause.

Step 1 — Simulation: Injecting FRM Slowness

A controlled simulation (FRM-Slowness) was triggered to reproduce an FRM application-layer degradation scenario — mimicking a slow DB query or external service dependency on the FRM processing path.

Step 2 — IBMB Journey Enters Unstable State: Slow Transactions Dominate

The IBMB Journey Overview reflects a different signature from the CBS failure cases: UEI at 9.31 and declining, Slow Transactions spike to 196 (up 99.49% vs yesterday), Response Time (95P) at 1.03 seconds, and TD at a relatively modest 5.13%. Crucially, the Journey Health panel shows both IBMB and FRM Transaction Health as Critical — CBS and Payment Switch remain healthy. 4 Critical Alerts active.

Step 3 — FRM Response Time 4.25s; CBS Healthy at 515ms

The Trends & E2E Transaction Flow panel makes the bottleneck unambiguous. FRM Response Time (95P) = 4.25 seconds (highlighted in orange) and IBMB Response Time = 4.30 seconds — nearly identical, confirming IBMB's total latency is being consumed entirely by FRM. Meanwhile CBS Response Time = 515ms (healthy, normal range). FRM TD is 2.11% and IBMB is 2.01% — slow but not failing fast, confirming FRM is processing but very slowly.

Step 4 — Distributed Trace Confirms FRM Span Consuming 98.7% of Transaction Time

The Trace Map for a sample transaction (c7f12093397912760fa1...) reveals the precise bottleneck: POST frm/{action} on the FRM service takes 5,788ms out of a total 5,863ms trace — 98.73% of the entire transaction duration. All FRM MSSQL sub-spans (transaction_risk_rules_db) are fast (<2ms each), confirming the slow path is not the database queries themselves but the FRM application processing logic between them.

Step 5 — MCP Root Cause Analysis with Proof Points

The following prompt was used in GitHub Copilot via the VuNet MCP Server:

"Please connect to ng2 instance. I notice some transactions slowdown in IBMB over the last 5 mins. Transactions connect from IBMB to CBS/FRM, can you please analyse the logs and search the exception if any for these transactions and come up with a quick RCA and recommendation why is there a slowness. Give me sufficient proof points."

MCP autonomously queried IBMB journey metrics, FRM slow transaction logs, CBS response data, and trace records, then produced a structured RCA with evidence:

Root Cause (identified by MCP):

IBMB (host: 172.16.68.168)
└── Calls FRM (host: 172.16.68.107)
    └── FRM takes 5,500–5,937ms to respond (normal: ~30–40ms)
        ├── Fast path (reject): 1,277ms — FRM validation/rule check is normal
        └── Slow path (approve/process): 5,500–5,900ms — FRM backend is degraded
            └── Root cause inside FRM: likely one of:
                1. Slow Oracle/DB query on the FRM transaction processing path
                2. FRM thread pool partially starved (some threads processing slowly)
                3. External service called by FRM during approval (e.g., sanctions list, scoring engine) is slow
                4. FRM GC pressure causing intermittent pauses (not a full stall, since rejections are fast)

Proof Points — FRM is the Bottleneck:

FRM slow transactions on host 172.16.68.107:

CBS responding in 630–1,120ms for AccountStatement — healthy, confirming the delay is squarely in FRM.

FRM TD Response Time (failures):

FRM failure response time (1,277ms) is far lower than FRM's success response time (5,500–5,900ms) — meaning FRM is fast to reject but extremely slow to approve/process. This is a strong indicator of a backend resource bottleneck on the processing path only (e.g., a slow DB query only hit on approval logic, not on early rejection/validation).

Key distinguishing factor from earlier outages:

• Use Case 2 (13:21 UTC): CBS hung completely — SocketTimeoutException at 1,000ms, no response at all

• This incident: FRM responding slowly but successfully (~5–6 seconds) — CBS is healthy

MCP Recommendations (Priority Order):

Key Insight: MCP identified FRM as the sole bottleneck by comparing FRM's rejection latency (1,277ms) against its approval latency (5,500–5,900ms) — a split that only appears when the bottleneck is on the approval/processing code path, not on the validation/rejection path. This level of differential analysis — automatically correlating slow transaction host logs, trace spans, CBS health checks, and FRM TAT percentiles — would require an experienced engineer 20–30 minutes of manual cross-dashboard investigation to replicate.

📄 Changelog

v2.2.0 (2026-03-18)

• ✅ Added vunet_fetch_datamodels tool — live data model discovery via /api/vuaccel/datamodel/

• ✅ Supports pagination, search, signal type filter, and ordering

• ✅ Fixed package.json bin entries (npm pkg fix)

v2.1.1 (2026-02-18)

• ✅ Updated repository URLs to correct GitHub organization

• ✅ Fixed package metadata

v2.1.0 (2026-02-17)

• ✅ Authentication improvements with proxy support

• ✅ Auto-reconnect on session expiry

• ✅ Better error handling

v2.0.8

• Initial stable release

• Multi-tenant support

• Comprehensive data model access

📝 License

MIT License - see LICENSE file.

🤝 Contributing

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📧 Support

• GitHub Issues: https://github.com/mithung-vunet/vunet-mcp-server/issues

• npm Package: https://www.npmjs.com/package/@mithung/vunet-mcp-server

🙏 Acknowledgments

• Built with @modelcontextprotocol/sdk

• Powered by Vunet vuSmartMaps

🔗 Links

• Vunet Systems: https://vunetsystems.com

• MCP Protocol: https://modelcontextprotocol.io

• npm Package: https://www.npmjs.com/package/@mithung/vunet-mcp-server

• GitHub: https://github.com/mithung/vunet-mcp-server

• Issues: https://github.com/mithung/vunet-mcp-server/issues

📞 Support

• Documentation: GitHub Wiki

• Issues: GitHub Issues

• Email: support@vunetsystems.com

Made with ❤️ by Vunet Systems