mcpulse-monitor Package – MCPulse Developer Docs

Installation

npm install mcpulse-monitor

✅ Zero dependencies — uses only Node.js built-in modules (http, https, crypto)

Quick Start

const MCPulseMonitor = require('mcpulse-monitor');

// Initialize
const monitor = new MCPulseMonitor({
  apiKey: process.env.MCPULSE_API_KEY
});

// Wrap your MCP server
monitor.wrap(yourMCPServer);

// Start monitoring
monitor.start();

That's it! Metrics will start flowing to your MCPulse dashboard.

Configuration Options

All configuration options with defaults and descriptions.

const monitor = new MCPulseMonitor({
  // ============================================
  // REQUIRED
  // ============================================
  apiKey: string,  // Your MCPulse API key from dashboard

  // ============================================
  // OPTIONAL
  // ============================================

  // Server identification
  serverId: string,  // Server ID (auto-generated if omitted)

  // Endpoint configuration
  endpoint: string,  // MCPulse API endpoint
                     // Default: 'https://stacks.polsia.app'

  // Reporting intervals
  reportingInterval: number,  // Batch send interval in ms
                              // Default: 60000 (1 minute)
                              // Recommendation: 30000-120000

  heartbeatInterval: number,  // Heartbeat ping interval in ms
                              // Default: 60000 (1 minute)
                              // Recommendation: 30000-300000

  // Buffer limits
  maxBufferedMetrics: number,  // Max metrics to buffer in memory
                               // Default: 1000
                               // Increase for high-traffic servers

  // Network timeouts
  timeout: number,  // API request timeout in ms
                    // Default: 5000
                    // Increase for slow networks

  // Logging
  silent: boolean  // Suppress all console logs
                   // Default: false
                   // Set to true in production for quiet operation
});

💡 Configuration Tips

• High-traffic servers: Increase maxBufferedMetrics to prevent data loss
• Slow networks: Increase timeout to avoid failed reports
• Production: Set silent: true to reduce console noise
• Real-time monitoring: Reduce reportingInterval to 30 seconds

API Methods

`wrap(server)`

Wrap an MCP server instance to automatically track all requests.

monitor.wrap(myMCPServer);

What it tracks:

• Response time for each request
• Success/failure status
• Error types and counts
• Tool names (if using MCP protocol)

`start()`

Start the monitoring service. Begins sending heartbeats and batched metrics.

monitor.start();

What happens:

• Starts heartbeat timer (sends periodic pings)
• Starts reporting timer (sends batched metrics)
• Metrics collected by wrap() are sent to MCPulse

`stop()`

Stop the monitor and flush any pending metrics. Call this during graceful shutdown.

// Graceful shutdown example
process.on('SIGTERM', async () => {
  console.log('Shutting down gracefully...');
  monitor.stop();
  process.exit(0);
});

What happens:

• Stops heartbeat and reporting timers
• Flushes any buffered metrics to MCPulse
• Prevents memory leaks

`getMetrics()`

Get a snapshot of current metrics. Useful for local debugging.

const metrics = monitor.getMetrics();
console.log(metrics);

Returns:

{
  "totalRequests": 1250,
  "successfulRequests": 1245,
  "failedRequests": 5,
  "errorRate": "0.40%",
  "avgResponseTime": 124,
  "minResponseTime": 8,
  "maxResponseTime": 2543,
  "errorsByType": {
    "TimeoutError": 3,
    "ValidationError": 2
  },
  "requestsByTool": {
    "getTool": 450,
    "listTools": 350,
    "callTool": 450
  },
  "lastHeartbeat": "2026-02-12T03:15:30.000Z"
}

How It Works

1

Wrapping

The wrap() method intercepts your MCP server's request handlers. Every incoming request is timed and tracked.

2

Tracking

Each request is categorized by success/failure, tool name, response time, and error type. Metrics are stored in memory.

3

Batching

Metrics are batched in memory and sent every 60 seconds (configurable) to minimize network overhead.

4

Resilience

If the MCPulse API is unreachable, metrics are buffered locally (up to maxBufferedMetrics) and retried with exponential backoff.

5

Heartbeat

Even during quiet periods, periodic heartbeat pings confirm your server is alive and responsive.

Performance Impact

CPU Overhead:

<0.1%

Memory Overhead:

<2MB

Network Usage:

<1KB/min

Troubleshooting

🔴 Monitor not sending metrics?

1. Check your API key:
```
echo $MCPULSE_API_KEY
```
Should start with mcpulse_sk_

2. Verify network connectivity:

curl https://stacks.polsia.app/api/mcpulse/health

3. Enable debug logging:

const monitor = new MCPulseMonitor({
  apiKey: '...',
  silent: false  // Remove this to see logs
});

4. Check server is registered:
Go to Dashboard and verify your server appears in the list.

⚠️ High memory usage?

If the monitor is using excessive memory, you're likely buffering too many metrics.

1. Reduce reporting interval:

reportingInterval: 30000  // Flush every 30 seconds instead of 60

2. Reduce buffer size:

maxBufferedMetrics: 500  // Buffer 500 metrics instead of 1000

3. Ensure graceful shutdown:

process.on('SIGTERM', () => {
  monitor.stop();  // Flushes buffer on shutdown
  process.exit(0);
});

📊 Metrics not showing in dashboard?

1. Wait 60 seconds: Metrics are batched and sent every 60 seconds by default.

2. Verify server ID matches:

const monitor = new MCPulseMonitor({
  apiKey: '...',
  serverId: 'exact-id-from-dashboard'  // Must match exactly
});

3. Check server is receiving requests: If your server has no traffic, only heartbeats are sent (no metrics).
4. Verify API key is correct: Wrong API key = metrics are silently dropped.

📘 TypeScript support?

Yes! Type definitions are included in the package.

import MCPulseMonitor from 'mcpulse-monitor';

const monitor = new MCPulseMonitor({
  apiKey: process.env.MCPULSE_API_KEY!,
  serverId: 'my-server',
  reportingInterval: 60000
});

Features

✓ Zero dependencies

✓ Non-intrusive

✓ Graceful failure

✓ Batched reporting

✓ Auto-retry with backoff

✓ TypeScript support

✓ Minimal config

✓ <0.1% CPU overhead

mcpulse-monitor