Shinzo
Python SDK for MCP server observability, built on OpenTelemetry. Gain insight into agent usage patterns, contextualize tool calls, and analyze server performance across platforms. Integrate with any OpenTelemetry ingest service including the Shinzo p
What is Shinzo?
Shinzo is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to python sdk for mcp server observability, built on opentelemetry. gain insight into agent usage patterns, contextualize tool calls, and analyze server performance across platforms. integrate with any o...
Python SDK for MCP server observability, built on OpenTelemetry. Gain insight into agent usage patterns, contextualize tool calls, and analyze server performance across platforms. Integrate with any OpenTelemetry ingest service including the Shinzo p
This server falls under the Monitoring & Observability category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Python SDK for MCP server observability, built on OpenTeleme
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx shinzo-pyConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Shinzo
Shinzo is a Python SDK that adds OpenTelemetry-based observability to MCP servers, giving developers deep insight into how AI agents interact with their tools. By wrapping any FastMCP or standard MCP server with a single function call, it automatically tracks request durations, error rates, tool call arguments, and session correlations. Telemetry can be streamed to the hosted Shinzo platform or any OTLP-compatible backend such as Grafana, Jaeger, or Honeycomb.
Prerequisites
- Python 3.9 or later
- An existing MCP server built with FastMCP or the standard MCP Python SDK
- pip or uv package manager
- An OTLP-compatible observability backend (optional — defaults to Shinzo's hosted service)
- An MCP-compatible client such as Claude Desktop or Cursor for testing
Install the Shinzo SDK
Install the shinzo package from PyPI using pip or uv. This adds the instrumentation library to your Python environment.
pip install shinzoInstrument your FastMCP server
Import instrument_server from shinzo and call it with your FastMCP instance before defining any tools. The SDK wraps the server transparently and begins collecting telemetry.
from mcp.server.fastmcp import FastMCP
from shinzo import instrument_server
mcp = FastMCP(name="my-mcp-server")
observability = instrument_server(mcp, config={
"server_name": "my-mcp-server",
"server_version": "1.0.0",
"sampling_rate": 1.0,
"enable_metrics": True,
"enable_tracing": True,
"enable_pii_sanitization": True
})
@mcp.tool()
def get_data(query: str) -> str:
return f"Result for: {query}"Configure a custom OTLP exporter (optional)
If you want to send telemetry to your own backend instead of the Shinzo hosted service, set the exporter_endpoint and authentication in the config dictionary.
observability = instrument_server(mcp, config={
"server_name": "my-mcp-server",
"server_version": "1.0.0",
"exporter_endpoint": "https://your-otlp-endpoint:4318",
"exporter_auth": {"type": "bearer", "token": "YOUR_TOKEN"},
"exporter_type": "otlp-http"
})Run your instrumented MCP server
Start your server normally. Shinzo will begin emitting traces and metrics for every tool invocation automatically.
python your_server.pyRegister with your MCP client
Add the instrumented server to your Claude Desktop or other MCP client configuration as you normally would. Observability is transparent to the client.
{
"mcpServers": {
"my-mcp-server": {
"command": "python",
"args": ["/path/to/your_server.py"]
}
}
}Shinzo Examples
Client configuration
Example Claude Desktop configuration for an MCP server instrumented with Shinzo.
{
"mcpServers": {
"my-mcp-server": {
"command": "python",
"args": ["/path/to/your_server.py"],
"env": {}
}
}
}Prompts to try
After instrumenting your server with Shinzo, use your AI client normally — observability is automatic. These prompts test that your tools are being tracked.
- "Use the get_data tool to fetch results for 'test query' and tell me what you got"
- "Call my tool three times with different inputs so I can see traces in Shinzo"
- "What tools does this MCP server expose?"Troubleshooting Shinzo
No telemetry appearing in the Shinzo dashboard after instrumentation
Check that instrument_server is called before the MCP server starts handling requests. Also verify the exporter_endpoint is reachable and that enable_tracing is set to True in the config.
PII data appearing in traces despite enable_pii_sanitization being True
The built-in sanitizer covers common patterns (emails, phone numbers, SSNs). For domain-specific sensitive fields, provide a custom pii_sanitizer function in the config that redacts your specific data patterns.
High memory usage when tracing servers with many concurrent requests
Reduce the sampling_rate (e.g., 0.1 for 10% sampling) and increase batch_timeout_ms to batch telemetry more aggressively. Also consider setting enable_argument_collection to False if tool arguments are large.
Frequently Asked Questions about Shinzo
What is Shinzo?
Shinzo is a Model Context Protocol (MCP) server that python sdk for mcp server observability, built on opentelemetry. gain insight into agent usage patterns, contextualize tool calls, and analyze server performance across platforms. integrate with any opentelemetry ingest service including the shinzo p It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Shinzo?
Follow the installation instructions on the Shinzo GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Shinzo?
Shinzo works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Shinzo free to use?
Yes, Shinzo is open source and available under the MIT license. You can use it freely in both personal and commercial projects.
Shinzo Alternatives — Similar Monitoring & Observability Servers
Looking for alternatives to Shinzo? Here are other popular monitoring & observability servers you can use with Claude, Cursor, and VS Code.
Netdata
★ 78.9kReal-time infrastructure monitoring with metrics, logs, alerts, and ML-based anomaly detection.
Kubeshark
★ 11.9keBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.
Mission Control
★ 4.9kSelf-hosted AI agent orchestration platform: dispatch tasks, run multi-agent workflows, monitor spend, and govern operations from one mission control dashboard.
Grafana
★ 3.0kThis MCP server enables natural-language querying of Grafana logs by automatically detecting log sources and service labels. It provides read-only access to log data with intelligent caching for efficient repeat queries.
Sentrux
★ 2.4kReal-time architectural sensor that helps AI agents close the feedback loop, enabling recursive self-improvement of code quality. Pure Rust.
OpenInference
★ 986OpenTelemetry Instrumentation for AI Observability
Browse More Monitoring & Observability MCP Servers
Explore all monitoring & observability servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Shinzo in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Shinzo?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.