Shinzo TypeScript SDK: Complete Observability for MCP Servers

The SDK provides OpenTelemetry-compatible instrumentation for TypeScript MCP servers. Gain insight into agent usage patterns, contextualize tool calls, and analyze performance of your servers across platforms. Instrumentation can be installed in servers in just a few steps with an emphasis on ease of use and flexibility.

Explore the docs »

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