Skip to main content

​
Prerequisites

Before you begin, make sure you have:
  • Node.js 18+ (for running Heimdall backend and frontend)
  • Python 3.9+ (if using the Python SDK)

​
Step 1: Start the Heimdall Stack

First, clone the Heimdall repository and start the backend and frontend servers.
The backend server receives OTLP traces from your instrumented applications.
cd backend
npm install
npm run dev
You should see:
╔═══════════════════════════════════════════════════════════╗
║                    HEIMDALL BACKEND                       ║
║                                                           ║
║  OTLP Endpoint:  http://localhost:4318/v1/traces          ║
║  API Endpoint:   http://localhost:4318/api                ║
║  Health Check:   http://localhost:4318/health             ║
║                                                           ║
║  Ready to receive traces from SDKs!                       ║
╚═══════════════════════════════════════════════════════════╝
The frontend provides a beautiful dashboard for viewing your traces.
cd frontend
npm install
npm run dev
Open http://localhost:5173 in your browser.

​
Step 2: Create Your Workspace

1

Create an Account

Navigate to http://localhost:5173 and sign up with your email and password.
2

Create an Organization

Organizations group your projects together. Give it a name like “My Company” or “Personal”.
3

Create a Project

Each project has a unique ID for trace collection. Create one for each service you want to monitor.
4

Get Your IDs

Go to Settings to find your Organization ID and Project ID. You’ll need these to configure the SDK.

​
Step 3: Install the SDK

Choose your language and install the Heimdall SDK: 
pip install hmdl

​
Step 4: Instrument Your Code

Add tracing to your MCP server with just a few lines of code: 
from hmdl import HeimdallClient, trace_mcp_tool

# Initialize the client
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"
)

# Decorate your MCP tools
@trace_mcp_tool()
def search_tool(query: str, limit: int = 10) -> dict:
    # Your tool logic here
    return {"results": [], "query": query, "limit": limit}

# Run your tool
result = search_tool("test query", limit=5)

# Flush traces before exit
client.flush()
Python SDK automatically captures parameter names using introspection.JavaScript SDK requires the paramNames option to display inputs as named objects instead of arrays.

​
Step 5: View Your Traces

  1. Go to the Heimdall dashboard at http://localhost:5173
  2. Navigate to Settings → Link SDK Project
  3. Click Link next to your SDK project to view its traces
  4. Go to Tracing to see all your traces
Congratulations! You’ve successfully set up Heimdall observability for your MCP server.

​
Next Steps

Python SDK Guide

Deep dive into Python SDK features and best practices.

JavaScript SDK Guide

Deep dive into JavaScript SDK features and best practices.

Environment Variables

Configure Heimdall using environment variables.

SDK Options

Explore all available SDK configuration options.