Skip to main content

​
Using the TypeScript SDK

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.
Building with Python? Check out the Python SDK for Python MCP server instrumentation.

​
Requirements

​
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}!` }
})
If your server does not call tools as above, please contact [email protected] so we can prioritize your method of calling server tools.

​
Environment Variables

For better security and configuration management, consider using 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

​
1. 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
})

​
2. 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)

​
Troubleshooting Installation

​
Module Resolution Issues

If you encounter module resolution errors:
  1. Check Node.js version: Ensure you’re using Node.js 18+.
  2. 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: You may need to use .js extensions in import paths, depending on your build setup.

​
Network Issues

If telemetry isn’t reaching the 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 [email protected] or check our GitHub repository.