Configuration

The Shinzo TypeScript SDK provides extensive configuration options to customize telemetry collection, data processing, and export behavior for your MCP server.

Basic Configuration

The minimal configuration requires only a few essential parameters:

import { instrumentServer } from "@shinzolabs/instrumentation-mcp"

const telemetry = instrumentServer(server, {
  serverName: "my-mcp-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: "your-ingest-token-here"
  }
})

TelemetryConfig Interface

The TelemetryConfig interface provides comprehensive configuration options:

Required Parameters

Parameter	Type	Description
`serverName`	`string`	Name of your MCP server
`serverVersion`	`string`	Version of your MCP server

Export Configuration

Parameter	Type	Default	Description
`exporterEndpoint`	`string`	-	OpenTelemetry collector endpoint URL
`exporterType`	`'otlp-http' \| 'otlp-grpc' \| 'console'`	`'otlp-http'`	Type of telemetry exporter
`exporterAuth`	`ExporterAuth`	-	Authentication configuration

Data Collection

Parameter	Type	Default	Description
`enableTracing`	`boolean`	`true`	Enable trace collection
`enableMetrics`	`boolean`	`true`	Enable metrics collection
`enableArgumentCollection`	`boolean`	`false`	Collect tool arguments in traces
`samplingRate`	`number`	`1.0`	Trace sampling rate (0.0 to 1.0)

Privacy & Processing

Parameter	Type	Default	Description
`enablePIISanitization`	`boolean`	`true`	Enable automatic PII sanitization
`PIISanitizer`	`PIISanitizer`	-	Custom PII sanitizer instance
`dataProcessors`	`((data: any) => any)[]`	`[]`	Custom data processing functions

Performance

Parameter	Type	Default	Description
`metricExportIntervalMs`	`number`	`5000`	Metric export interval in milliseconds
`batchTimeoutMs`	`number`	`2000`	Batch timeout in milliseconds

Authentication Configuration

Bearer Token Authentication (required for the Shinzo Platform)

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: process.env.TOKEN
  }
})

API Key Authentication

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://custom-endpoint.com/v1",
  exporterAuth: {
    type: "apiKey",
    apiKey: process.env.API_KEY
  }
})

Basic Authentication

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://custom-endpoint.com/v1",
  exporterAuth: {
    type: "basic",
    username: process.env.USERNAME,
    password: process.env.PASSWORD
  }
})

Exporter Types

OTLP HTTP Exporter (Default)

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "otlp-http",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: ...
})

OTLP gRPC Exporter

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: "otlp-grpc",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_grpc",
  exporterAuth: ...
})

Console Exporter (Development)

Perfect for development and debugging:

const telemetry = instrumentServer(server, {
  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
})

Privacy Configuration

Built-in PII Sanitization

The SDK automatically detects and sanitizes common PII patterns:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  enablePIISanitization: true, // Default
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Custom PII Sanitizer

Implement your own PII sanitization logic:

import { PIISanitizer } from "@shinzolabs/instrumentation-mcp"

class CustomPIISanitizer implements PIISanitizer {
  sanitize(data: any): any {
    // Your custom sanitization logic
    if (typeof data === 'string') {
      return data.replace(/\b\d{4}-\d{4}-\d{4}-\d{4}\b/g, '****-****-****-****')
    }
    return data
  }
}

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  PIISanitizer: new CustomPIISanitizer(),
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Data Processing

Custom Data Processors

Add custom logic to process telemetry data before export:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  dataProcessors: [
    // Remove sensitive tool arguments
    (data) => {
      if (data['mcp.tool.name'] === 'sensitive_operation') {
        for (const key of Object.keys(data)) {
          if (key.startsWith('mcp.request.argument')) {
            delete data[key]
          }
        }
      }
      return data
    },

    // Add custom metadata
    (data) => {
      data['environment'] = process.env.NODE_ENV || 'development'
      data['deployment.version'] = process.env.DEPLOYMENT_VERSION
      return data
    },

    // Filter out health check spans
    (data) => {
      if (data['mcp.tool.name'] === 'health_check') {
        return null // Return null to skip this data
      }
      return data
    }
  ],
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Sampling Configuration

Fixed Sampling Rate

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  samplingRate: 0.1, // Sample 10% of traces
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Environment-based Sampling

const getSamplingRate = () => {
  switch (process.env.NODE_ENV) {
    case 'production': return 0.05 // 5% in production
    case 'staging': return 0.25    // 25% in staging
    case 'development': return 1.0 // 100% in development
    default: return 0.1            // 10% default
  }
}

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  samplingRate: getSamplingRate(),
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Performance Tuning

Batch Configuration

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  batchTimeoutMs: 1000,        // Export every 1 second
  metricExportIntervalMs: 10000, // Export metrics every 10 seconds
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Memory Optimization

For high-throughput servers:

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  samplingRate: 0.01,           // Low sampling rate
  enableArgumentCollection: false, // Skip argument collection
  batchTimeoutMs: 500,          // Frequent exports
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Environment-Specific Configuration

Development Configuration

const isDevelopment = process.env.NODE_ENV === 'development'

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: "1.0.0",
  exporterType: isDevelopment ? "console" : "otlp-http",
  exporterEndpoint: isDevelopment ? undefined : "https://api.app.shinzo.ai/telemetry/ingest_http",
  enableMetrics: !isDevelopment, // Disable metrics for console output
  samplingRate: isDevelopment ? 1.0 : 0.1,
  enableArgumentCollection: isDevelopment,
  exporterAuth: isDevelopment ? undefined : {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

Production Configuration

const telemetry = instrumentServer(server, {
  serverName: "my-server",
  serverVersion: process.env.APP_VERSION || "1.0.0",
  exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  },
  samplingRate: 0.05,
  enableArgumentCollection: false,
  enablePIISanitization: true,
  batchTimeoutMs: 2000,
  metricExportIntervalMs: 30000,
  dataProcessors: [
    (data) => {
      data['environment'] = 'production'
      data['service.instance.id'] = process.env.HOSTNAME
      return data
    }
  ]
})

Configuration Validation

The SDK validates configuration at startup and will log warnings for common issues:

Missing required parameters
Invalid sampling rates (must be between 0.0 and 1.0)
Incompatible exporter/configuration combinations
Network connectivity issues

MCP Analytics

TypeScript SDK

Python SDK

Configuration

Configuration

Basic Configuration

TelemetryConfig Interface

Required Parameters

Export Configuration

Data Collection

Privacy & Processing

Performance

Authentication Configuration

Bearer Token Authentication (required for the Shinzo Platform)

API Key Authentication

Basic Authentication

Exporter Types

OTLP HTTP Exporter (Default)

OTLP gRPC Exporter

Console Exporter (Development)

Privacy Configuration

Built-in PII Sanitization

Custom PII Sanitizer

Data Processing

Custom Data Processors

Sampling Configuration

Fixed Sampling Rate

Environment-based Sampling

Performance Tuning

Batch Configuration

Memory Optimization

Environment-Specific Configuration

Development Configuration

Production Configuration

Configuration Validation

​Configuration

​Basic Configuration

​TelemetryConfig Interface

​Required Parameters

​Export Configuration

​Data Collection

​Privacy & Processing

​Performance

​Authentication Configuration

​Bearer Token Authentication (required for the Shinzo Platform)

​API Key Authentication

​Basic Authentication

​Exporter Types

​OTLP HTTP Exporter (Default)

​OTLP gRPC Exporter

​Console Exporter (Development)

​Privacy Configuration

​Built-in PII Sanitization

​Custom PII Sanitizer

​Data Processing

​Custom Data Processors

​Sampling Configuration

​Fixed Sampling Rate

​Environment-based Sampling

​Performance Tuning

​Batch Configuration

​Memory Optimization

​Environment-Specific Configuration

​Development Configuration

​Production Configuration

​Configuration Validation

Configuration

Basic Configuration

TelemetryConfig Interface

Required Parameters

Export Configuration

Data Collection

Privacy & Processing

Performance

Authentication Configuration

Bearer Token Authentication (required for the Shinzo Platform)

API Key Authentication

Basic Authentication

Exporter Types

OTLP HTTP Exporter (Default)

OTLP gRPC Exporter

Console Exporter (Development)

Privacy Configuration

Built-in PII Sanitization

Custom PII Sanitizer

Data Processing

Custom Data Processors

Sampling Configuration

Fixed Sampling Rate

Environment-based Sampling

Performance Tuning

Batch Configuration

Memory Optimization

Environment-Specific Configuration

Development Configuration

Production Configuration

Configuration Validation