​
Installation

The Shinzo TypeScript SDK provides automatic instrumentation for MCP servers built with the @modelcontextprotocol/sdk. Get started with comprehensive telemetry in just a few minutes.

​
Requirements

  • Node.js: Version 18 or higher
  • TypeScript: Version 4.5 or higher (if using TypeScript)
  • MCP SDK: @modelcontextprotocol/sdk version 1.15.1 or higher

​
Package Installation

Install the Shinzo instrumentation SDK using your preferred package manager: 
npm install @shinzolabs/instrumentation-mcp

​
Peer Dependencies

The SDK requires the MCP SDK as a peer dependency. If you haven’t already installed it: 
npm install @modelcontextprotocol/sdk

​
Basic Setup

Once installed, instrument your MCP server with just a few lines of code: 
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { instrumentServer } from "@shinzolabs/instrumentation-mcp"

// Create your MCP server
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
  description: "My instrumented MCP server"
})

// Add telemetry instrumentation
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"
  }
})

// Continue with your normal server setup
server.tool("hello", {
  description: "Say hello",
  inputSchema: {
    type: "object",
    properties: {
      name: { type: "string" }
    }
  }
}, async (args) => {
  return { content: `Hello, ${args.name}!` }
})

​
Environment Variables

For better security and configuration management, use environment variables: 
# .env file
SHINZO_TOKEN=your-ingest-token-here
SHINZO_ENDPOINT=https://api.app.shinzo.ai/telemetry/ingest_http

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

const telemetry = instrumentServer(server, {
  serverName: "my-mcp-server",
  serverVersion: "1.0.0",
  exporterEndpoint: process.env.SHINZO_ENDPOINT,
  exporterAuth: {
    type: "bearer",
    token: process.env.SHINZO_TOKEN
  }
})

​
Verification

To verify the installation is working correctly:

​
1. Check Console Output

The SDK logs initialization information: 
[INFO] Shinzo telemetry initialized for server: my-mcp-server
[INFO] Exporting to: https://api.app.shinzo.ai/telemetry/ingest_http

​
2. Test with Console Exporter

For development, use the console exporter to see telemetry locally: 
const telemetry = instrumentServer(server, {
  serverName: "my-mcp-server",
  serverVersion: "1.0.0",
  exporterType: "console", // Outputs to console instead of HTTP
  enableMetrics: false // Console exporter doesn't support metrics
})

​
3. Execute a Tool

Run your server and execute any tool. You should see telemetry data in:
  • Console output (if using console exporter)
  • Shinzo Platform dashboard (if using HTTP exporter)

​
TypeScript Configuration

If you’re using TypeScript, ensure your tsconfig.json includes the correct settings: 
{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true,
    "strict": true
  }
}

​
Build Configuration

​
ES Modules

The SDK is built as ES modules. Ensure your package.json includes: 
{
  "type": "module"
}

​
CommonJS Support

If you need CommonJS support, you can use dynamic imports: 
// CommonJS usage
async function initTelemetry() {
  const { instrumentServer } = await import("@shinzolabs/instrumentation-mcp")

  const telemetry = instrumentServer(server, {
    // configuration
  })
}

​
Docker Installation

If deploying with Docker, include the SDK in your Dockerfile: 
FROM node:18

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies including Shinzo SDK
RUN npm install

# Copy source code
COPY . .

# Build if using TypeScript
RUN npm run build

CMD ["node", "dist/server.js"]

​
Troubleshooting Installation

​
Module Resolution Issues

If you encounter module resolution errors:
  1. Check Node.js version: Ensure you’re using Node.js 18+
  2. Verify package.json: Make sure type: "module" is set
  3. Update dependencies: Run npm update to get latest versions

​
Type Errors

For TypeScript type errors:
  1. Install type definitions: npm install @types/node
  2. Update TypeScript: Ensure you’re using TypeScript 4.5+
  3. Check imports: Use .js extensions in import paths

​
Network Issues

If telemetry isn’t reaching Shinzo Platform:
  1. Check firewall: Ensure outbound HTTPS connections are allowed
  2. Verify endpoint: Confirm the endpoint URL is correct
  3. Test connectivity: Try curl https://api.app.shinzo.ai/health

​
Next Steps

Now that you have the SDK installed:

Configuration

Learn about all available configuration options
Need help? Contact us at austin@shinzolabs.com or check our GitHub repository.