Installation

pnpm add @shinzolabs/instrumentation-mcp

Usage

For the simplest configuration, just pass in the server name, version, and exporter endpoint:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { instrumentServer, TelemetryConfig } from "@shinzolabs/instrumentation-mcp"

const NAME = "my-mcp-server"
const VERSION = "1.0.0"

const server = new McpServer({
  name: NAME,
  version: VERSION,
  description: "Example MCP server with telemetry"
})

// Use TelemetryConfig to set configuration options
const telemetryConfig: TelemetryConfig = {
  serverName: NAME,
  serverVersion: VERSION,
  exporterEndpoint: "http://localhost:4318/v1" // OpenTelemetry collector endpoint - /trace and /metrics are added automatically
}

// Initialize telemetry
const telemetry = instrumentServer(server, telemetryConfig)

// Add tools using the tool method
server.tool(...)

The TelemetryConfig exposes a number of other options for precise and expansive telemetry processing:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { instrumentServer, TelemetryConfig } from "@shinzolabs/instrumentation-mcp"

const NAME = "my-other-mcp-server"
const VERSION = "1.0.0"

const server = new McpServer({
  name: NAME,
  version: VERSION,
  description: "Example MCP server with telemetry"
})

const telemetryConfig: TelemetryConfig = {
  serviceName: NAME,
  serviceVersion: VERSION,
  exporterEndpoint: "http://localhost:4318/v1", // OpenTelemetry collector endpoint
  exporterAuth: {
    type: "bearer",
    token: process.env.OTEL_AUTH_TOKEN
  },
  enablePIISanitization: false,
  enableTracing: false,
  samplingRate: 0.7,
  dataProcessors: [
    (telemetryData: any) => {
      if (telemetryData['mcp.tool.name'] === "sensitive_operation") {
        for (const key of Object.keys(telemetryData)) {
          if (key.startsWith('mcp.request.argument')) delete telemetryData[key]
        }
      }
      return telemetryData
    }
  ]
}

const telemetry = instrumentServer(server, telemetryConfig)

// Add tools using the tool method
server.tool(...)

Configuration Options

The TelemetryConfig interface provides comprehensive configuration options for customizing telemetry behavior:

TelemetryConfig Properties

Property	Type	Required	Default	Description
`serverName`	`string`	✅	-	Name of the MCP server
`serverVersion`	`string`	✅	-	Version of the MCP server
`exporterEndpoint`	`string`	⚠️	-	OpenTelemetry collector OTLP endpoint URL (required unless using console exporter)
`exporterAuth`	`ExporterAuth`	❌	-	Authentication configuration for the exporter
`samplingRate`	`number`	❌	`1.0`	Trace sampling rate (0.0 to 1.0)
`metricExportIntervalMs`	`number`	❌	`5000`	Metric export interval in milliseconds
`enablePIISanitization`	`boolean`	❌	`true`	Enable automatic PII sanitization
`enableArgumentCollection`	`boolean`	❌	`false`	Enable collection of tool arguments in traces
`dataProcessors`	`((data: any) => any)[]`	❌	`[]`	Array of custom data processing functions
`exporterType`	`'otlp-http' \| 'otlp-grpc' \| 'console'`	❌	`'otlp-http'`	Type of telemetry exporter
`enableMetrics`	`boolean`	❌	`true`	Enable metrics collection
`enableTracing`	`boolean`	❌	`true`	Enable tracing collection
`batchTimeoutMs`	`number`	❌	`2000`	Batch timeout in milliseconds
`PIISanitizer`	`PIISanitizer`	❌	-	Custom PII sanitizer instance

ExporterAuth Configuration

The exporterAuth property supports multiple authentication methods:

Auth Type	Properties	Description
`bearer`	`token: string`	Bearer token authentication
`apiKey`	`apiKey: string`	API key authentication
`basic`	`username: string, password: string`	Basic HTTP authentication

Usage Examples

Minimal Configuration

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "http://localhost:4318/v1" // OpenTelemetry collector endpoint
}

Bearer Token Authentication

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.example.com/v1",
  exporterAuth: {
    type: "bearer",
    token: process.env.OTEL_AUTH_TOKEN
  }
}

Custom Data Processing

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "http://localhost:4318/v1", // OpenTelemetry collector endpoint
  dataProcessors: [
    (data) => {
      // Remove sensitive parameters
      if (data['mcp.tool.name'] === 'sensitive_tool') {
        delete data['mcp.request.argument.password']
      }
      return data
    }
  ]
}

Console Development Setup

const telemetryConfig: TelemetryConfig = {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "console",
  enableMetrics: false, // Console exporter doesn't support metrics
  samplingRate: 1.0 // Sample all traces in development
}

Contributing

Contributions are welcome! Please see the Contributing Guide in the main repository.

License

This package is distributed under the MIT License.

Shinzo TS

README