Heimdall is a comprehensive observability platform designed for monitoring Model Context Protocol (MCP) servers and AI/LLM applications. Built on OpenTelemetry standards, it provides real-time tracing, metrics, and insights into your AI infrastructure.

• 🔍 Real-time Tracing - Track every tool call, resource access, and prompt execution
• 📊 Dashboard Analytics - Visualize latency, error rates, and usage patterns
• 🔌 Easy Integration - Simple SDK decorators for Python and JavaScript/TypeScript
• 🏠 Self-hosted - Run entirely on your own infrastructure
• 📈 OpenTelemetry Native - Built on industry-standard observability protocols

• Track Users - Associate traces with user identities for user-level analytics (currently all requests are shown as anonymous).
• Evaluate - LLM evaluation and quality scoring, including human annotation.
• Add Cloud Host Server - Managed cloud deployment.

Currently we only support self-hosted deployment. The architecture is as follows:

┌─────────────────┐     OTLP/HTTP      ┌─────────────────┐
│   MCP Server    │ ──────────────────▶│  Heimdall       │
│   + SDK         │    Port 4318       │  Backend        │
└─────────────────┘                    └────────┬────────┘
                                                │
                                                │ REST API
                                                │
                                       ┌────────▼────────┐
                                       │  Heimdall       │
                                       │  Frontend       │
                                       │  Port 5173      │
                                       └─────────────────┘

📖 For detailed setup instructions, see QUICKSTART.md

• Node.js 18+
• Python 3.9+ (for Python SDK)

cd backend
npm install
npm run dev

cd frontend
npm install
npm run dev

1. Navigate to http://localhost:5173
2. Create an account with your email and password
3. Create an Organization - this groups your projects together
4. Create a Project - each project has a unique ID for trace collection

After creating your organization and project, go to Settings to find:

• Organization ID - Your organization identifier
• Project ID - Your project identifier

You'll need these IDs to configure the SDK.

Heimdall provides SDKs for instrumenting your MCP servers:

from hmdl import HeimdallClient, trace_mcp_tool

# Initialize client with your organization and project IDs
client = HeimdallClient(
    endpoint="http://localhost:4318",
    org_id="your-org-id",           # From Settings page
    project_id="your-project-id",   # From Settings page
    service_name="my-mcp-server",
    environment="development"
)

@trace_mcp_tool()
def search_tool(query: str, limit: int = 10) -> dict:
    return {"results": [], "query": query, "limit": limit}

result = search_tool("test", limit=5)
client.flush()

Note: Python SDK automatically captures parameter names using introspection. Inputs are displayed as named objects: {"query": "test", "limit": 5}.

import { HeimdallClient, traceMCPTool } from 'hmdl';

// Initialize client with your organization and project IDs
const client = new HeimdallClient({
  endpoint: "http://localhost:4318",
  orgId: "your-org-id",           // From Settings page
  projectId: "your-project-id",   // From Settings page
  serviceName: "my-mcp-server",
  environment: "development"
});

const searchTool = traceMCPTool(
  async (query: string, limit: number = 10) => ({ results: [], query, limit }),
  { name: "search-tool", paramNames: ["query", "limit"] }
);

await searchTool("test", 5);
await client.flush();

Note: Use the paramNames option to display inputs as named objects (e.g., {"query": "test", "limit": 5}) instead of arrays (["test", 5]).

You can also configure the SDK using environment variables:

export HEIMDALL_ENDPOINT="http://localhost:4318"
export HEIMDALL_ORG_ID="your-org-id"
export HEIMDALL_PROJECT_ID="your-project-id"
export HEIMDALL_SERVICE_NAME="my-mcp-server"
export HEIMDALL_ENVIRONMENT="development"
export HEIMDALL_ENABLED="true"

Then simply initialize the client without arguments:

# Python
client = HeimdallClient()

// JavaScript/TypeScript
const client = new HeimdallClient();

heimdall/
├── backend/          # OTLP receiver and API server
├── frontend/         # React dashboard
├── tests/            # SDK integration tests
├── QUICKSTART.md     # Detailed setup guide
└── README.md         # This file

heimdall-python/      # Python SDK
heimdall-js/          # JavaScript/TypeScript SDK

Test the SDK integration with the backend:

# Python SDK test
cd tests
source .venv/bin/activate
python test_python_sdk.py

# JavaScript SDK test
cd tests
npm run test:js

• 📖 Full Documentation - Comprehensive guides and API reference
• 🚀 Quick Start Guide - Get up and running in 5 minutes
• 🐍 Python SDK - Python SDK on PyPI
• 📦 JavaScript SDK - JavaScript/TypeScript SDK on npm

Contributions are welcome! Please feel free to submit a Pull Request.

• 📧 Email: [email protected]
• 🌐 Website: tryheimdall.com
• 📖 Documentation: docs.tryheimdall.com
• 🐛 Issues: GitHub Issues

This project is licensed under the MIT License - see the LICENSE file for details.