delta0-inc/heimdall

Overview

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.

Key Features

• 🔍 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

TODO

• [ ] 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.

Architecture

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      │
                                       └─────────────────┘

Quick Start

📖 For detailed setup instructions, see QUICKSTART.md

Prerequisites

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

1. Start the Backend

cd backend
npm install
npm run dev

2. Start the Frontend

cd frontend
npm install
npm run dev

3. Create Organization and Project

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

4. Get Your Configuration

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.

SDK Integration

Heimdall provides SDKs for instrumenting your MCP servers:

Python Example

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

JavaScript/TypeScript Example

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

Using Environment Variables

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

Configuration

Environment Variables

Client Configuration Options

Wrapper/Decorator Options

trace_mcp_tool / traceMCPTool

observe (general-purpose)

Project Structure

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

Running Tests

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

Documentation

• 📖 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

Contributing

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

Support & Contact

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

License

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