MCP Monitoring SDK for Node.js

A lightweight monitoring SDK for Model Context Protocol (MCP) servers. Track errors, performance, and tool executions with real-time insights.

Installation

npm install @mcp-monitoring/sdk

Quick Start

import { init, error, info, trackToolExecution } from '@mcp-monitoring/sdk'

// Initialize the SDK with your API key
init({
  apiKey: 'your-api-key-here',
  endpoint: 'https://your-monitoring-endpoint.com/api/v1', // optional
  serverId: 'my-mcp-server', // optional, defaults to MCP_SERVER_ID env var
})

// Track events
error('Database connection failed', { database: 'users', error: 'ECONNREFUSED' })
info('User authenticated', { userId: '123', method: 'oauth' })

// Track tool execution
trackToolExecution('read_file', {
  duration: 150,
  success: true,
  input_size: 1024,
  output_size: 2048,
  parameters: { path: '/home/user/document.txt' }
})

Configuration

interface MCPMonitoringConfig {
  apiKey: string              // Required: Your MCP Monitoring API key
  endpoint?: string           // Optional: API endpoint (default: http://localhost:8080/api/v1)
  projectId?: number          // Optional: Project ID
  serverId?: string           // Optional: Server identifier (default: MCP_SERVER_ID env var)
  flushInterval?: number      // Optional: How often to send events in ms (default: 5000)
  maxBatchSize?: number       // Optional: Max events per batch (default: 100)
}

API Reference

Basic Event Tracking

// Track custom events
track({
  level: 'error',
  message: 'Something went wrong',
  context: { userId: '123' },
  mcp_context: {
    tool_name: 'my-tool',
    server_id: 'my-server'
  }
})

// Convenience methods
error('Error message', context, mcpContext)
warning('Warning message', context, mcpContext)
info('Info message', context, mcpContext)
debug('Debug message', context, mcpContext)

Tool Execution Tracking

// Manual tracking
trackToolExecution('file_reader', {
  duration: 150,
  success: true,
  input_size: 1024,
  output_size: 2048,
  parameters: { path: '/file.txt' }
})

// Automatic wrapper (recommended)
const result = await wrapToolExecution('file_reader', async () => {
  // Your tool logic here
  return await readFile('/file.txt')
}, { path: '/file.txt' })

Manual Flushing

// Force send all pending events
await flush()

// Clean shutdown
await close()

MCP Integration Examples

Basic MCP Server

import { Server } from '@modelcontextprotocol/sdk/server/index.js'
import { init, wrapToolExecution, error } from '@mcp-monitoring/sdk'

// Initialize monitoring
init({
  apiKey: process.env.MCP_MONITORING_API_KEY!,
  serverId: 'my-file-server'
})

const server = new Server(
  {
    name: 'my-file-server',
    version: '1.0.0',
  },
  {
    capabilities: {
      tools: {},
    },
  }
)

// Wrap your tool handlers
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params

  try {
    return await wrapToolExecution(name, async () => {
      switch (name) {
        case 'read_file':
          return await readFile(args.path)
        case 'write_file':
          return await writeFile(args.path, args.content)
        default:
          throw new Error(`Unknown tool: ${name}`)
      }
    }, args)
  } catch (err) {
    error(`Tool execution failed: ${name}`, { 
      toolName: name, 
      arguments: args,
      error: err.message 
    })
    throw err
  }
})

Error Handling

import { error, warning } from '@mcp-monitoring/sdk'

try {
  await dangerousOperation()
} catch (err) {
  error('Operation failed', {
    operation: 'dangerousOperation',
    error: err.message,
    stack: err.stack
  }, {
    tool_name: 'my-tool',
    custom_data: { retryCount: 3 }
  })
  throw err
}

// Track warnings for non-fatal issues
if (response.warnings.length > 0) {
  warning('API returned warnings', {
    warnings: response.warnings,
    endpoint: '/api/data'
  })
}

Environment Variables

• MCP_SERVER_ID: Default server identifier
• MCP_MONITORING_API_KEY: API key (alternative to config)
• MCP_MONITORING_ENDPOINT: API endpoint (alternative to config)

Best Practices

1. Initialize Early: Call init() as early as possible in your application
2. Use Tool Wrappers: Use wrapToolExecution() for automatic performance tracking
3. Include Context: Always provide relevant context in your events
4. Handle Errors Gracefully: The SDK handles network failures internally
5. Clean Shutdown: Call close() on process exit for reliable event delivery

Event Levels

• error: System errors, exceptions, failures
• warning: Non-fatal issues, deprecations, performance concerns
• info: General operational events, successful operations
• debug: Detailed diagnostic information

License

MIT - see LICENSE file for details