shinzo-ts

Shinzo: Complete Observability for MCP Servers

Shinzo is the first observability solution purpose-built for MCP servers with complete OpenTelemetry compatibility. 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 »

🤖 About Shinzo

Shinzo is a complete observability platform for developers and publishers building MCP (Model Context Protocol) servers and agentic AI systems, with the goal to put powerful, privacy-conscious telemetry and analysis tools directly in the hands of server developers. All components adhere to OpenTelemetry conventions, making it easy to connect Shinzo to other OpenTelemetry-compatible software.

🏗️ System Architecture

• Drop-In Instrumentation: Drop-in OpenTelemetry-compatible instrumentation for MCP servers. Install with a single command to auto-instrument your server and export telemetry to the collector of your choice.
• Telemetry Collector: High-performance OpenTelemetry backend service with support for data sanitization, secure storage, and configurable retention attributes.
• Analytics Dashboard: Frontend dashboard for real-time analytics, trace analysis, performance profiling, tool usage stats, and more.

✨ Key Features

• Automatic Instrumentation: One line of code gives you instant instrumentation for your MCP server's capabilities.
• Configurable Telemetry, Anonymous by Default: Built-in PII sanitization and data processing features help you stay compliant with GDPR, CCPA/CPRA and other data privacy regulation effortlessly.
• Full Control: All components of Shinzo can be self-hosted with our sustainable use license or cloud hosted through Shinzo Labs.
• Custom Analytics Dashboards: Self-hosted, real-time dashboards for tool usage, performance, and traces.
• OpenTelemetry-Compatible: Since the entire system meets OpenTelemetry standard conventions, developers can mix-and-match our modules with any OpenTelemetry-compatible service.

⚙️ Setup

1. Install & Use in Your Own MCP Server

Add Shinzo to your MCP server project:

pnpm add @shinzolabs/instrumentation-mcp
# or
npm install @shinzolabs/instrumentation-mcp

Then instrument your MCP server using the SDK. Example:

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(...)

See packages/instrumentation-mcp/examples/basic-usage.ts for a full working example.

2. Local Development & Testing

Clone the repo and install dependencies:

git clone https://github.com/shinzo-labs/shinzo-ts.git
cd shinzo
pnpm install

Build the package:

pnpm build

Run the test suite:

pnpm test

You can also run specific test scripts (see package.json for all options):

pnpm test:unit    # Run only unit tests
pnpm test:integration  # Run only integration tests
pnpm lint         # Lint the codebase

🗺️ Roadmap

Note: For the complete roadmap timeline with all issues, see the Roadmap page on Github.

• ✅ Phase 0 (June 2025)

  • ✅ 🏗️ System Architecture Design
  • ✅ 🤝 Contributor Operations

• ✅ Phase 1 (July 2025)

  • ✅ 📏 OpenTelemetry MCP Semantic Conventions
  • ✅ 🛠️ TypeScript Instrumentation SDK

• ⬜️ Phase 2 (August 2025)

  • ⬜️ 📡 Telemetry Collector
  • ⬜️ 📊 Analytics Dashboard
  • ⬜️ 🛡️ Complete Server Instrumentation
  • ⬜️ 🏅 SOC2 Type I Certification

• ⬜️ Phase 3 (September 2025)

  • ⬜️ 🐍 Python Instrumentation SDK
  • ⬜️ 🧠 Agentic Analysis
  • ⬜️ 🗣️ User Elicitation Management

• ⬜️ Phase 4 (Q4 2025)

  • ⬜️ 🦦 Go Instrumentation SDK
  • ⬜️ 💠 C# Instrumentation SDK
  • ⬜️ 🏅 SOC2 Type II Certification

• ⬜️ Phase 5 & Beyond (2026+)

  • ⬜️ 🚨 Incident Alerting System
  • ⬜️ 🚀 Server Config & Deployment Console
  • ⬜️ 🏭 Industry Vertical Solutions
  • ⬜️ ☕ Java Instrumentation SDK
  • ⬜️ 🦀 Rust Instrumentation SDK

🤝 Contributing

Contributions to Shinzo are appreciated, whether you are a veteran building sophisticated enterprise AI agent systems or a newcomer just testing the waters. Shinzo accepts contributions both in terms of direct code contributions as well as non-technical support like community engagement, user testing, and professional partnerships. Feel free to join the conversation on our Discord server and checkout the Contributing page to learn how you can become a contributor.

📄 License

Shinzo is fair-code software distributed under the Sustainable Use License and Shinzo Enterprise License.

• Source Available: Always visible source code
• Self-Hostable: Deploy anywhere
• Extensible: Add your own features or functionality

Enterprise licenses are available for additional features and support through Shinzo Labs.

We believe that the fair-code license model offers a strong compromise between democratizing the benefits of open software while ensuring long-term sustainability of software maintenance and operations. Our specific license model is adapted from n8n, with additional context for the origin of the licenses here.

Some of this software's capabilities enable developers and businesses to collect data on usage of products by respective end users. Shinzo Labs accepts no responsibility for how this software is used by other developers, and by using this software you accept all terms of the relevant licenses, including the section on No Liability.

📞 Contact

Contact Austin Born (austin@shinzolabs.com, @austinbuilds) if you have any questions or comments related to this software.

📚 Additional Resources

• Model Context Protocol
• OpenTelemetry
• GDPR
• CCPA/CPRA

(back to top)