> ## 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.
# Quick Start Guide
> Get your MCP server instrumented and sending data to Shinzo in under 5 minutes.
# Quick Start Guide
Get up and running with Shinzo Platform in just a few minutes. This guide will walk you through instrumenting your MCP server and viewing product insights in the dashboard.
## Prerequisites
Choose one based on your language:
**TypeScript/JavaScript:**
* [Node.js 18](https://nodejs.org/en/download) or higher
* An existing MCP server using [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/typescript-sdk)
**Python:**
* [Python 3.10](https://www.python.org/downloads/) or higher
* An existing MCP server using [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) or [FastMCP](https://github.com/jlowin/fastmcp)
**Both:**
* A Shinzo Platform account (sign up at [app.shinzo.ai](https://app.shinzo.ai))
## Step 1: Install the SDK
Install the Shinzo instrumentation SDK in your MCP server project:
```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
```
```bash pip theme={null}
pip install shinzo
```
## Step 2: Get Your Ingest Token
1. Sign up or log in at [app.shinzo.ai](https://app.shinzo.ai).
2. Navigate to Settings → Ingest Tokens.
3. Copy your ingest token (it will look like `abc123def456...`).
## Step 3: Instrument Your Server
Add telemetry to your MCP server with just a few lines of code:
```typescript TypeScript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { instrumentServer } from "@shinzolabs/instrumentation-mcp"
const server = new McpServer({
name: "my-awesome-server",
version: "1.0.0",
description: "My MCP server with telemetry"
})
// Add this after creating your server
const telemetry = instrumentServer(server, {
serverName: server.name,
serverVersion: server.version,
exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
exporterAuth: {
type: "bearer",
token: "your-ingest-token-here" // Replace with your actual token
}
})
// Continue with your existing server setup
server.tool("example_tool", {
description: "An example tool",
inputSchema: {
type: "object",
properties: {
message: { type: "string" }
}
}
}, async (args) => {
return { content: `Hello, ${args.message}!` }
})
```
```python Python (MCP SDK) theme={null}
from mcp.server import Server
from shinzo import instrument_server
# Create your MCP server
server = Server("my-awesome-server")
# Instrument it with Shinzo
observability = instrument_server(
server,
config={
"server_name": "my-awesome-server",
"server_version": "1.0.0",
"exporter_auth": {
"type": "bearer",
"token": "your-ingest-token-here" # Replace with your actual token
}
}
)
# Define your tools
@server.call_tool()
async def example_tool(message: str) -> str:
"""An example tool."""
return f"Hello, {message}!"
# Clean shutdown
async def shutdown():
await observability.shutdown()
```
```python Python (FastMCP) theme={null}
from mcp.server.fastmcp import FastMCP
from shinzo import instrument_server
# Create FastMCP server
mcp = FastMCP(name="my-awesome-server")
# Instrument it with Shinzo
observability = instrument_server(
mcp,
config={
"server_name": "my-awesome-server",
"server_version": "1.0.0",
"exporter_auth": {
"type": "bearer",
"token": "your-ingest-token-here" # Replace with your actual token
}
}
)
# Define your tools
@mcp.tool()
def example_tool(message: str) -> str:
"""An example tool."""
return f"Hello, {message}!"
# Run the server
if __name__ == "__main__":
mcp.run()
```
Replace `your-ingest-token-here` with your actual ingest token from Step 2.
## Step 4: Start Your Server
Run your instrumented MCP server as usual. Telemetry data will automatically be collected and sent to Shinzo whenever tools are executed.
Support for other capabilities like Resources, Prompts, and User Elicitation is coming soon!
## Step 5: View Your Data
1. Go to [app.shinzo.ai](https://app.shinzo.ai).
2. Navigate to the Dashboard to see real-time metrics.
3. Check the Traces page to see individual tool executions.
4. Visit Resources to monitor server performance.
## Example: Complete MCP Server
Here's a complete example of an instrumented MCP server:
```typescript TypeScript theme={null}
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
import { instrumentServer } from "@shinzolabs/instrumentation-mcp"
const server = new McpServer({
name: "weather-server",
version: "1.0.0",
description: "Weather information MCP server"
})
// Instrument the server
const telemetry = instrumentServer(server, {
serverName: "weather-server",
serverVersion: "1.0.0",
exporterEndpoint: "https://api.app.shinzo.ai/telemetry/ingest_http",
exporterAuth: {
type: "bearer",
token: process.env.SHINZO_TOKEN
}
})
// Add a weather tool
server.tool("get_weather", {
description: "Get weather for a city",
inputSchema: {
type: "object",
properties: {
city: { type: "string" }
},
required: ["city"]
}
}, async (args) => {
// Simulate API call
const weather = {
city: args.city,
temperature: Math.round(Math.random() * 30 + 10),
condition: "sunny"
}
return {
content: `Weather in ${weather.city}: ${weather.temperature}°C, ${weather.condition}`
}
})
// Start the server
async function main() {
const transport = new StdioServerTransport()
await server.connect(transport)
}
main().catch(console.error)
```
```python Python (MCP SDK) theme={null}
import os
import random
import asyncio
from mcp.server import Server
from shinzo import instrument_server
# Create your MCP server
server = Server("weather-server")
# Instrument the server
observability = instrument_server(
server,
config={
"server_name": "weather-server",
"server_version": "1.0.0",
"exporter_auth": {
"type": "bearer",
"token": os.getenv("SHINZO_TOKEN")
}
}
)
# Add a weather tool
@server.call_tool()
async def get_weather(city: str) -> str:
"""Get weather for a city."""
# Simulate API call
temperature = random.randint(10, 40)
condition = "sunny"
return f"Weather in {city}: {temperature}°C, {condition}"
# Run the server
async def main():
# Your server setup and connection logic here
try:
# Server connection logic would go here
await asyncio.sleep(60) # Keep server running
finally:
await observability.shutdown()
if __name__ == "__main__":
asyncio.run(main())
```
```python Python (FastMCP) theme={null}
import os
import random
from mcp.server.fastmcp import FastMCP
from shinzo import instrument_server
# Create FastMCP server
mcp = FastMCP(name="weather-server")
# Instrument the server
observability = instrument_server(
mcp,
config={
"server_name": "weather-server",
"server_version": "1.0.0",
"exporter_auth": {
"type": "bearer",
"token": os.getenv("SHINZO_TOKEN")
}
}
)
# Add a weather tool
@mcp.tool()
def get_weather(city: str) -> str:
"""Get weather for a city."""
# Simulate API call
temperature = random.randint(10, 40)
condition = "sunny"
return f"Weather in {city}: {temperature}°C, {condition}"
# Run the server
if __name__ == "__main__":
mcp.run()
```
## Next Steps
Now that your server is instrumented:
Learn about advanced TypeScript SDK configuration options.
Learn about advanced Python SDK configuration options.
Discover all the insights available in the Shinzo Platform dashboard.
## Troubleshooting
### Not seeing data?
1. **Check your ingest token**: Make sure it's correct and active.
2. **Verify network access**: Ensure your server can reach `api.app.shinzo.ai`.
3. **Check console logs**: Use `exporterType: "console"` to check logs for anomalies.
### Performance concerns?
The SDK is designed to be lightweight with minimal performance impact:
* Telemetry is exported in batches
* Network calls are non-blocking
* Sampling can be configured to reduce data volume
Need help? Contact us at [austin@shinzolabs.com](mailto:austin@shinzolabs.com)