> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shinzo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install and set up the Shinzo TypeScript SDK for MCP server instrumentation.

# 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.

<Note>
  Building with Python? Check out the [Python SDK](/sdk/python/installation) for Python MCP server instrumentation.
</Note>

## Requirements

* **Node.js**: Version [18 or higher](https://nodejs.org/en/download)
* **TypeScript**: Version [4.5 or higher](https://www.typescriptlang.org/download/)
* **MCP SDK**: [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk) version 1.15.1 or higher

## Package Installation

Install the Shinzo instrumentation SDK using your preferred package manager:

<CodeGroup>
  ```bash npm theme={null}
  npm install @shinzolabs/instrumentation-mcp
  ```

  ```bash pnpm theme={null}
  pnpm add @shinzolabs/instrumentation-mcp
  ```

  ```bash yarn theme={null}
  yarn add @shinzolabs/instrumentation-mcp
  ```
</CodeGroup>

## Peer Dependencies

The SDK requires the MCP SDK as a peer dependency. If you haven't already installed it:

<CodeGroup>
  ```bash npm theme={null}
  npm install @modelcontextprotocol/sdk
  ```

  ```bash pnpm theme={null}
  pnpm add @modelcontextprotocol/sdk
  ```

  ```bash yarn theme={null}
  yarn add @modelcontextprotocol/sdk
  ```
</CodeGroup>

## Basic Setup

Once installed, instrument your MCP server with just a few lines of code:

```typescript theme={null}
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}!` }
})
```

<Warning>
  If your server does not call tools as above, please contact [austin@shinzolabs.com](mailto:austin@shinzolabs.com) so we can prioritize your method of calling server tools.
</Warning>

## Environment Variables

For better security and configuration management, consider using environment variables:

```bash theme={null}
# .env file
SHINZO_TOKEN=your-ingest-token-here
SHINZO_ENDPOINT=https://api.app.shinzo.ai/telemetry/ingest_http
```

```typescript theme={null}
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:

```typescript theme={null}
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:

<CardGroup cols={1}>
  <Card title="Configuration" icon="gear" href="/sdk/typescript/configuration">
    Learn about all available configuration options.
  </Card>
</CardGroup>

Need help? Contact us at [austin@shinzolabs.com](mailto:austin@shinzolabs.com) or check our [GitHub repository](https://github.com/shinzo-labs/shinzo-ts).