Agentlens MCP Server

AgentLens is a self-hosted observability platform for autonomous AI agents. Think of it as Datadog, but for agents — not servers.

It captures telemetry (LLM calls, tool usage, token consumption) and turns it into actionable insights:

• 📊 Session traces — See exactly what your agent did, step by step
• 🛑 Agent Loop Intervention — First-of-its-kind "Kill Switch". Safely stall looping agents at the network proxy layer and instantly inject a natural language hint via the Dashboard to steer them back on track.
• 🔁 Loop detection — Automatically detect when agents get stuck in repetitive cycles
• 💰 Dynamic Cost Tracking — Instead of hardcoding AI model prices (which change constantly), AgentLens features a background NestJS PricingService that syncs daily via Cron with the open-source LiteLLM JSON registry. It automatically fuzzy-matches your agent's current model to its real-time cost constants and calculates accurate USD (inputTokens * inputPrice) + (outputTokens * outputPrice) immediately during ingestion, giving you zero-maintenance billing observability.
• 🧠 RL-powered insights — Q-learning scores each tool based on real outcomes
• 📈 Retention — Track how often users return to agentic workflows

Architecture

┌──────────────────────────────────────────────────────────────┐
│  docker compose up                                            │
│                                                                │
│  ┌─────────┐  ┌─────────┐  ┌───────────┐  ┌──────────────┐   │
│  │ Postgres │  │  Redis  │  │    API    │  │  Dashboard   │   │
│  │  :5432   │  │  :6379  │  │   :9471   │  │    :9472     │   │
│  └─────────┘  └─────────┘  └─────┬─────┘  └──────────────┘   │
│                                   │                            │
│                            ┌──────┴──────┐                     │
│                            │  LLM Proxy  │                     │
│                            │    :9473    │                     │
│                            └─────────────┘                     │
└──────────────────────────────────────────────────────────────┘

Quick Start

Prerequisites

• Docker and Docker Compose
• Node.js 18+ (for local development)

1. Clone and start

git clone https://github.com/itzvenkat/agentlens.git
cd agentlens
cp .env.example .env.development
docker compose up -d

All 5 services start up. Wait ~30 seconds for everything to be healthy, then open:

• Dashboard → http://localhost:9472
• API → http://localhost:9471/health
• Proxy → http://localhost:9473/health

2. Create a project

Every agent/app gets its own project with a unique API key:

curl -X POST http://localhost:9471/v1/projects \
  -H "X-Master-Key: agentlens_master_dev_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-first-agent", "description": "Testing AgentLens"}'

The response includes your API key (starts with al_). Save it — it's only shown once.

3. Start sending data

Pick the integration method that matches your setup:

How to Integrate

AgentLens offers four ways to connect, from zero-code to full programmatic control:

Option A: LLM Proxy

Best for: Desktop apps, IDEs, and anything where you can't modify code.

The proxy sits between your client and the LLM API. It forwards requests unchanged and silently logs telemetry to AgentLens.

Step 1: Add your API key to .env.development:

AGENTLENS_API_KEY=al_your_key_here

Step 2: Restart the proxy:

docker compose up -d proxy

Step 3: Point your client to the proxy:

The proxy auto-detects the provider (OpenAI, Anthropic, Google, OpenRouter, Ollama) based on request headers and URL patterns.

How it works: Client → localhost:9473 → proxy logs the request → forwards to real API → returns response → logs the response.

Option B: SDK

Best for: TypeScript/Node.js apps where you want fine-grained control.

npm install @itzvenkat0/agentlens-sdk

OpenAI:

import OpenAI from 'openai';
import { AgentLensClient, wrapOpenAI } from '@itzvenkat0/agentlens-sdk';

const lens = new AgentLensClient({
  apiKey: 'al_your_key_here',
  endpoint: 'http://localhost:9471',
});

const openai = wrapOpenAI(lens, new OpenAI());

// That's it — all calls are now automatically traced
const result = await openai.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What is 2+2?' }],
});

Anthropic:

import Anthropic from '@anthropic-ai/sdk';
import { AgentLensClient, wrapAnthropic } from '@itzvenkat0/agentlens-sdk';

const lens = new AgentLensClient({ apiKey: 'al_...', endpoint: 'http://localhost:9471' });
const anthropic = wrapAnthropic(lens, new Anthropic());

Vercel AI SDK:

import { generateText, streamText } from 'ai';
import { AgentLensClient, wrapVercelAI } from '@itzvenkat0/agentlens-sdk';

const lens = new AgentLensClient({ apiKey: 'al_...', endpoint: 'http://localhost:9471' });
const ai = wrapVercelAI(lens, { generateText, streamText });

Generic (any provider via fetch):

import { AgentLensClient, wrapFetch } from '@itzvenkat0/agentlens-sdk';

const lens = new AgentLensClient({ apiKey: 'al_...', endpoint: 'http://localhost:9471' });
globalThis.fetch = wrapFetch(lens, globalThis.fetch);
// All subsequent fetch() calls to known LLM APIs are auto-traced

Manual spans:

const trace = lens.trace('task-123');
const span = trace.span('tool', 'read_file');
// ... do work ...
span.end({ status: 'ok', toolName: 'read_file' });
await trace.end('success');

See libs/sdk/README.md for the full API reference.

Option C: MCP Server

Best for: MCP-compatible agents (Claude Desktop, Copilot, Gemini CLI, Cursor).

Install globally:

npm install -g @itzvenkat0/agentlens-mcp-server

Then add to your MCP config:

{
  "mcpServers": {
    "agentlens": {
      "command": "agentlens-mcp",
      "env": {
        "AGENTLENS_API_URL": "http://localhost:9471",
        "AGENTLENS_API_KEY": "al_your_key_here"
      }
    }
  }
}

The agent gets three tools: report_progress, report_result, and report_error.

Config file locations:

Option D: REST API

Best for: Any language, any framework, full control.

curl -X POST http://localhost:9471/v1/ingest \
  -H "X-API-Key: al_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "spans": [{
      "traceId": "task-123",
      "spanId": "span-1",
      "type": "llm",
      "model": "gpt-4o",
      "inputTokens": 150,
      "outputTokens": 80,
      "durationMs": 1200,
      "status": "ok"
    }]
  }'

Dashboard

Open http://localhost:9472 to see:

• Overview — KPIs, RL tool ratings, recent sessions
• Sessions (with Kill Switch) — Filterable list with full trace data. Includes a Halt & Steer UI to actively intervene in looping agents and inject custom developer hints.
• Tool Efficiency — Which tools help agents succeed vs. cause loops
• Retention — Daily agent activity and return rates

API Reference

All endpoints require X-API-Key header except those marked as public.

Configuration

Copy .env.example to .env.development and edit:

Deploy

Docker (recommended)

# Production
cp .env.example .env.production
# Edit .env.production with real credentials

NODE_ENV=production docker compose up -d

Local Development

# Install everything
npm install --legacy-peer-deps
cd dashboard && npm install && cd ..

# Start only infrastructure
docker compose up -d postgres redis

# Start API with hot reload
npm run start:api:dev

# Start dashboard (separate terminal)
cd dashboard && npm run dev

# Start proxy (separate terminal)
npm run start:proxy

Commands

Project Structure

agentlens/
├── apps/
│   ├── api/                    # NestJS REST API
│   │   └── src/
│   │       ├── auth/           # API key auth, project management
│   │       ├── ingest/         # Telemetry ingestion, PII scrubbing
│   │       ├── analytics/      # Queries, aggregations, SSE
│   │       ├── processor/      # Loop detection, RL engine, daily aggregation
│   │       └── config/         # Multi-env config with Joi validation
│   ├── mcp-server/             # MCP server (stdio transport)
│   └── proxy/                  # Transparent LLM Proxy
├── libs/
│   ├── common/                 # Shared entities, DTOs, constants
│   └── sdk/                    # TypeScript SDK (@itzvenkat0/agentlens-sdk)
│       ├── client.ts           # Core client (batching, flush, PII)
│       ├── trace.ts            # Trace + Span classes
│       └── wrappers/           # OpenAI, Anthropic, Vercel AI, fetch
├── dashboard/                  # Next.js 15 analytics dashboard
├── docker/                     # Dockerfiles, init SQL
├── .github/workflows/          # CI + npm publish
├── .env.example                # Config template
└── docker-compose.yml          # Full stack (one command)

How the RL Engine Works

AgentLens learns from session outcomes using Q-learning:

1. Reward signal — Each completed session gets a score based on:

   • Success/failure (+1.0 / −0.5)
   • Token efficiency (budget usage)
   • Loop penalty (−0.3 per detected loop)
   • Speed bonus (faster = higher)

2. Q-value updates — Each tool's Q-value is updated incrementally:

   Q(tool) = Q(tool) + α × (reward - Q(tool))
   

   Tools closer to the outcome get more credit (γ = 0.95).

3. Dashboard insights — Q-values surface as ranked tool recommendations, showing which tools to keep, improve, or deprecate.

Tech Stack

Packages

License

MIT