Tetragon MCP Server (WIP)

A Model Context Protocol (MCP) server that exposes Tetragon's kernel-level security observability data to any LLM provider or AI application that supports the MCP specification.

🚀 Quick Start

Prerequisites

• Go 1.24+
• Docker
• kubectl (for Kubernetes deployment)
• Network access to your Tetragon clusters (for multi-cluster setup)

Single Cluster Development Setup

# Clone the repository
git clone https://github.com/calghar/tetragon-mcp.git
cd tetragon-mcp

# Start development environment (includes Tetragon + MCP server + test workloads)
make dev-setup

# Test the server
make dev-test

Multi-Cluster Setup

# Build the binary
make build

# Create multi-cluster configuration
cp examples/multi-cluster-config.yaml ~/.tetragon-mcp.yaml

# Edit configuration with your cluster details
vim ~/.tetragon-mcp.yaml

# Run with multi-cluster configuration
./tetragon-mcp --config ~/.tetragon-mcp.yaml

Multi-cluster configuration example:

clusters:
  - name: "production"
    address: "prod-tetragon.example.com:54321"
    auth:
      type: "tls"
      tls:
        cert_file: "/path/to/prod-client.crt"
        key_file: "/path/to/prod-client.key"
    labels:
      environment: "production"
      region: "us-west-2"
  
  - name: "staging"
    address: "staging-tetragon.example.com:54321"
    auth:
      type: "none"
    labels:
      environment: "staging"

mcp:
  address: ":8080"
events:
  buffer_size: 50000
  retention_seconds: 7200

Production Deployment

Local Deployment

# Build and deploy locally
make image IMAGE_TAG=production
./scripts/deploy-docker.sh --type production --config /path/to/production-config.yaml

Docker Container Deployment

# Using Docker Compose (recommended for production)
cd deploy/docker
docker-compose -f docker-compose-production.yml up -d

# Using standalone Docker
docker run -d \
  --name tetragon-mcp \
  -p 8080:8080 \
  -v /opt/tetragon-mcp/config.yaml:/etc/tetragon-mcp/config.yaml:ro \
  -v /opt/tetragon-mcp/certs:/etc/certs:ro \
  --restart unless-stopped \
  tetragon-mcp:latest

Kubernetes Deployment

# Deploy to Kubernetes cluster
kubectl apply -f deploy/kubernetes/multi-cluster-deployment.yaml

# Using Helm (for single cluster)
make deploy NAMESPACE=your-namespace

Cloud Deployment

TBD

📖 What is Tetragon MCP Server?

This server bridges Tetragon (runtime security observability) with AI/LLM applications using the Model Context Protocol.

Key Features

• Real-time Security Data: Stream kernel-level events from Tetragon
• Universal LLM Integration: Compatible with any MCP-supporting LLM provider (Claude, OpenAI, custom apps)
• Dual Transport Modes: Stdio mode for LLM integrations, HTTP mode for testing and APIs
• Advanced Filtering: Time-based, process-based, namespace-based, and cluster-based filtering
• Multiple Event Types: Process execution, network activity, file access, kernel probes
• Multi-Cluster Support: Connect to multiple Tetragon instances across different clusters
• Flexible Authentication: Support for TLS, mTLS, and token-based authentication
• Flexible Deployment: Deploy locally, as Docker container, on Kubernetes, or in the cloud
• Production Ready: Kubernetes-native with Helm charts, monitoring, and security policies
• Easy Development: One-command setup with kind clusters

Use Cases

• Cross-Cluster Security Analysis: "Show me suspicious process executions across all production clusters in the last hour"
• Multi-Environment Incident Response: "What network connections did this compromised pod make in both staging and production?"
• Centralized Compliance Monitoring: "List all file access events across development, staging, and production for auditing"
• Advanced Threat Hunting: "Find processes with unusual privilege escalation patterns across all monitored clusters"
• Environment Correlation: "Compare security events between staging and production clusters to identify deployment risks"

🏗️ Architecture

Single Cluster Deployment

The MCP server connects LLM applications to a single Tetragon instance:

LLM/AI Tool ↔ Tetragon MCP Server ↔ Tetragon (DaemonSet) ↔ eBPF Kernel Events

• LLM applications communicate via MCP Protocol (JSON-RPC over stdio or HTTP)
• MCP server connects to Tetragon via gRPC (port 54321)
• Tetragon collects kernel events via eBPF

Multi-Cluster Deployment

• Each cluster runs its own Tetragon instance
• MCP server connects to multiple Tetragon endpoints simultaneously
• Events are enriched with cluster metadata (name, labels, region)
• LLM applications can query across all clusters or filter by specific clusters

🔧 Development

Build from Source

# Build binary
make build

# Run tests
make test-all

# Run with hot reload
make dev

Available Commands

make help                 # Show all available commands

# Development
make dev-setup           # Setup complete dev environment  
make dev-clean           # Clean up dev environment
make dev-logs            # View server logs

# Testing  
make test                # Unit tests
make test-integration    # Integration tests
make test-e2e           # End-to-end tests
make test-all           # All tests

# Production
make deploy             # Deploy with Helm
make image              # Build production image

🤖 MCP Integration

The Tetragon MCP Server supports both stdio and HTTP transport modes, making it compatible with any LLM provider that implements the Model Context Protocol specification.

Stdio Mode (Recommended for LLM Integrations)

Most LLM applications (Claude Desktop, OpenAI tools, custom applications) use stdio mode where they launch the MCP server as a subprocess:

Claude Desktop

Add to your Claude Desktop config (~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "tetragon": {
      "command": "/path/to/tetragon-mcp",
      "args": ["--stdio", "--config", "/path/to/config.yaml"],
      "env": {
        "TETRAGON_MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Other MCP-Compatible LLM Providers

For other LLM applications that support MCP stdio transport:

# Generic stdio usage
/path/to/tetragon-mcp --stdio --config /path/to/config.yaml

# With inline configuration
/path/to/tetragon-mcp --stdio --tetragon-address localhost:54321 --log-level info

HTTP Mode (For Custom Applications and Testing)

HTTP mode is useful for testing, debugging, and custom applications that prefer REST APIs:

# Start in HTTP mode (default)
./tetragon-mcp --config /path/to/config.yaml

# Access via HTTP on port 8080
curl -X POST http://localhost:8080/mcp/v1/resources/list -d '{}'

Integration Examples

Python Integration:

import requests

# List available resources
response = requests.post("http://your-server:8080/mcp/v1/resources/list", json={})
resources = response.json()["resources"]

# Read security events
response = requests.post("http://your-server:8080/mcp/v1/resources/read", json={
    "uri": "tetragon://events/process-exec",
    "filters": {"limit": 10, "start_time": "2025-01-20T10:00:00Z"}
})
events = response.json()["contents"]

Testing with curl

After running make dev-setup, you can test the MCP API directly:

# Health check
curl -X POST http://localhost:30080/health

# Initialize MCP connection
curl -X POST http://localhost:30080/mcp/v1/initialize \
  -H "Content-Type: application/json" -d '{}'

# List available resources
curl -X POST http://localhost:30080/mcp/v1/resources/list \
  -H "Content-Type: application/json" -d '{}'

# Read process execution events
curl -X POST http://localhost:30080/mcp/v1/resources/read \
  -H "Content-Type: application/json" \
  -d '{"uri": "tetragon://events/process-exec", "filters": {"limit": 5}}' | jq .

# Read all events with time filter
curl -X POST http://localhost:30080/mcp/v1/resources/read \
  -H "Content-Type: application/json" \
  -d '{"uri": "tetragon://events", "filters": {"limit": 10}}' | jq .

# Browse events by time buckets (NEW!)
curl -X POST http://localhost:30080/mcp/v1/resources/read \
  -H "Content-Type: application/json" \
  -d '{"uri": "tetragon://events/buckets/daily"}' | jq .

# Access events for a specific date
curl -X POST http://localhost:30080/mcp/v1/resources/read \
  -H "Content-Type: application/json" \
  -d '{"uri": "tetragon://events/2025-09-27"}' | jq .

# Access filtered events for a specific hour
curl -X POST http://localhost:30080/mcp/v1/resources/read \
  -H "Content-Type: application/json" \
  -d '{"uri": "tetragon://events/2025-09-27/14/process-exec"}' | jq .

🪣 Time Bucket Navigation

The server supports hierarchical time bucket navigation for easy data exploration:

Navigation Resources

• tetragon://events/buckets/daily - Browse available days with events
• tetragon://events/buckets/hourly - Browse available hours with events
• tetragon://events/by-type - Browse events by type first, then by time
• tetragon://events/recent - Recent events from the last 24 hours

Direct Time Access

• tetragon://events/2025-09-27 - All events for a specific date
• tetragon://events/2025-09-27/14 - Events for a specific hour (14:00-15:00)
• tetragon://events/2025-09-27/process-exec - Specific event type for a date
• tetragon://events/2025-09-27/14/kprobe - Specific event type for an hour

Benefits:

• Data-driven: Only shows time periods that actually contain events
• Browsable: Navigate like a filesystem hierarchy
• Efficient: Uses indexed lookups for fast bucket discovery
• Backward Compatible: All existing URIs continue to work
• Flexible: Multiple navigation patterns (time-first vs type-first)

📖 Documentation

• Getting Started - Quick setup and basic usage
• Deployment Guide - Complete deployment options (development to production)
• Testing Guide - Testing strategies and MCP client integration
• Developer Guide - Development setup and coding standards
• Contributing Guide - Contribution guidelines
• Security Policy - Security reporting and best practices

🤝 Contributing

Please see the Contributing Guide and Developer Guide to get started.

Quick Development Workflow

# 1. Fork and clone
git clone https://github.com/YOUR_USERNAME/tetragon-mcp.git

# 2. Create feature branch
git checkout -b feature/your-feature

# 3. Setup development environment
make dev-setup

# 4. Make changes and test
make test-all

# 5. Submit PR
git push origin feature/your-feature

🙏 Acknowledgments

• Tetragon - Runtime security observability platform
• Model Context Protocol - Standard for AI tool integration
• Cilium - eBPF-based networking and security