# AgentLens (npm · @agentkitai/agentlens-mcp)

Tamper-evident, SHA-256 hash-chained audit trail and observability for AI agents.

- Trust score: 67/100 (medium)
- Change this week: +24
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `@agentkitai/agentlens-mcp`: 67/100 (this document), [markdown](https://verifymcp.io/servers/agentkitai-agentlens/agentkitai-agentlens-mcp.md), [page](https://verifymcp.io/servers/agentkitai-agentlens/agentkitai-agentlens-mcp)

## Channel facts

- Registry: `npm`
- Package: `@agentkitai/agentlens-mcp`
- Version: `0.13.7`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 87/100
  - No malware found by supply-chain analysis.
  - Only part of the dependency tree could be resolved (97 of 101), so this covers what we could see, not the whole tree.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (97 of 101), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 45/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 36 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 62/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 4294 tokens (~195/item across 22 items; 22 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add agentkitai-agentlens -- npx -y @agentkitai/agentlens-mcp
```

### Codex

```bash
codex mcp add agentkitai-agentlens -- npx -y @agentkitai/agentlens-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agentkitai-agentlens": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@agentkitai/agentlens-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add agentkitai-agentlens --command npx --arg -y --arg @agentkitai/agentlens-mcp
```

### Hermes

```yaml
mcp_servers:
  agentkitai-agentlens:
    command: "npx"
    args: ["-y", "@agentkitai/agentlens-mcp"]
```

### Other

```json
{
  "mcpServers": {
    "agentkitai-agentlens": {
      "command": "npx",
      "args": [
        "-y",
        "@agentkitai/agentlens-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 67, −2)

No change was recorded against any check on this day. Supply Chain Security went from 97 to 87. Other categories moved too: Stability & Change Management rose 4.

### 2026-08-02 (score 69, +36)

- [security regression] Provenance: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Known CVEs: unverified → partial
- [functional improvement] License: unverified → pass
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] Schema quality: unverified → good
- [functional improvement] Dependency health: unverified → partial
- [functional] Licence: MIT

### 2026-08-01 (score 33, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-07-31 (score 18, −7)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-30 (score 25, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-27 (score 43)

First indexed and scored.

## MCP tools (22)

### `agentlens_session_start` (~66 tokens)

Start a new AgentLens monitoring session. Returns a sessionId to use for subsequent events.

Input parameters:

- `agentId` (string, required): Unique identifier for the agent
- `agentName` (string): Human-readable agent name
- `tags` (array): Tags for categorizing this session

### `agentlens_log_event` (~101 tokens)

Log an event to an active AgentLens session.

Input parameters:

- `eventType` (string, required): Event type (e.g., tool_call, tool_response, custom)
- `metadata` (object): Arbitrary metadata (tags, labels, correlation IDs)
- `payload` (object, required): Event payload — structure depends on eventType
- `sessionId` (string, required): Session ID from agentlens_session_start
- `severity` (string): Severity level (default: info)

### `agentlens_session_end` (~54 tokens)

End an active AgentLens monitoring session.

Input parameters:

- `reason` (string, required): Reason for ending the session
- `sessionId` (string, required): Session ID to end
- `summary` (string): Optional summary of the session

### `agentlens_query_events` (~62 tokens)

Query events from an AgentLens session.

Input parameters:

- `eventType` (string): Filter by event type
- `limit` (number): Maximum number of events to return (default: 50)
- `sessionId` (string, required): Session ID to query events from

### `agentlens_log_llm_call` (~261 tokens)

Log a complete LLM call (request + response) to an active AgentLens session. Emits paired llm_call and llm_response events.

Input parameters:

- `completion` (required): The completion content returned by the model
- `costUsd` (number, required): Cost of this call in USD
- `finishReason` (string, required): Stop reason (e.g., "stop", "length", "tool_use", "content_filter", "error")
- `latencyMs` (number, required): Latency in milliseconds
- `messages` (array, required): The prompt messages sent to the model
- `model` (string, required): Model identifier (e.g., "claude-opus-4-6", "gpt-4o")
- `parameters` (object): Model parameters (temperature, maxTokens, etc.)
- `provider` (string, required): LLM provider name (e.g., "anthropic", "openai", "google")
- `sessionId` (string, required): Session ID from agentlens_session_start
- `systemPrompt` (string): System prompt (if separate from messages)
- `toolCalls` (array): Tool calls requested by the model
- `tools` (array): Tool/function definitions provided to the model
- `usage` (object, required): Token usage counts

### `agentlens_reflect` (~308 tokens)

Analyze behavioral patterns from agent sessions — error patterns, tool sequences, cost analysis, and performance trends.

\**When to use:** To identify recurring errors and their root causes (error_patterns), to understand cost drivers and optimize model usage (cost_analysis), to discover common tool usage chains and their success rates (tool_sequences), or to track performance over time (performance_trends).

\**What it returns:** A list of structured insights with type, summary, data, and confidence score, plus metadata about how many sessions/events were analyzed. Each analysis type returns different data shapes.

\**Example:** agentlens_reflect({ analysis: "error_patterns", agentId: "my-agent", from: "2026-01-01" }) → returns recurring error patterns with counts, first/last seen, and affected sessions.

Input parameters:

- `agentId` (string): Filter analysis to a specific agent
- `analysis` (string, required): Type of analysis to run: error_patterns (recurring errors), tool_sequences (common tool usage patterns), cost_analysis (cost breakdown and trends), performance_trends (success rate and duration trend…
- `from` (string): Start of time range (ISO 8601)
- `limit` (number): Maximum number of results to return (default: 20)
- `params` (object): Additional parameters (e.g., { model: "gpt-4o" } for cost_analysis)
- `to` (string): End of time range (ISO 8601)

### `agentlens_optimize` (~183 tokens)

Get cost optimization recommendations. Analyzes LLM call patterns and suggests cheaper model alternatives.

\**When to use:** To identify cost-saving opportunities by switching expensive models to cheaper alternatives for tasks that don't require the most capable model. Analyzes call complexity (simple/moderate/complex) and success rates.

\**What it returns:** A list of model switch recommendations with estimated monthly savings, confidence levels, and success rate comparisons. Sorted by potential savings.

\**Example:** agentlens_optimize({ period: 7 }) → returns recommendations like "Switch gpt-4o → gpt-4o-mini for SIMPLE tasks, saving $89/month".

Input parameters:

- `limit` (number): Max recommendations to return (default: 5, max: 50)
- `period` (number): Analysis period in days (default: 7, max: 90)

### `agentlens_context` (~231 tokens)

Retrieve cross-session context for a topic — related session summaries and lessons ranked by relevance.

\**When to use:** At the start of a session to load relevant history, when building a system prompt with past experience, when starting work on a topic the agent has handled before, or to audit what happened with a specific topic.

\**What it returns:** Related sessions (with summaries, key events, and relevance scores) and related lessons, all ranked by relevance to the topic. Includes an overall summary.

\**Example:** agentlens_context({ topic: "database migrations", limit: 5 }) → returns past sessions about DB migrations with key events, plus any lessons learned about migrations.

Input parameters:

- `agentId` (string): Filter by agent ID
- `from` (string): Start date filter (ISO 8601)
- `limit` (number): Maximum number of sessions to include (default: 5)
- `to` (string): End date filter (ISO 8601)
- `topic` (string, required): Topic to retrieve context for (natural language)
- `userId` (string): Filter by user ID

### `agentlens_health` (~159 tokens)

Check the health score of the current agent. Returns overall score (0-100), trend, and dimension breakdown.

\**When to use:** To assess the current health and performance of the agent, to check if error rates or latency are degrading, or to get a quick overview of agent reliability metrics.

\**What it returns:** An overall health score (0-100), a trend indicator (improving/stable/degrading), and a breakdown by five dimensions: error rate, cost efficiency, tool success, latency, and completion rate.

\**Example:** agentlens_health({ window: 7 }) → returns health score with dimension breakdown for the last 7 days.

Input parameters:

- `window` (number): Rolling window in days (default: 7)

### `agentlens_replay` (~272 tokens)

Replay a past session as a structured, human-readable timeline.

\**When to use:** To review what happened in a previous session — understand failures, decision patterns, timing, or cost accumulation. Great for debugging or post-mortem analysis.

\**What it returns:** A session header (agent, status, duration, cost, event counts) followed by numbered, timestamped steps with event type icons and context annotations.

\**Parameters:**
\- sessionId (required): The session to replay
\- fromStep/toStep: Replay a specific step range
\- eventTypes: Comma-separated filter (e.g., "llm_call,tool_call")
\- summaryOnly: Set true to get just the summary header (fast for large sessions)

\**Example:** agentlens_replay({ sessionId: "ses_abc123", summaryOnly: true }) → returns session summary without steps.

Input parameters:

- `eventTypes` (string): Comma-separated event types to filter (e.g., "llm_call,tool_call")
- `fromStep` (integer): Start step number (0-based)
- `sessionId` (string, required): Session ID to replay
- `summaryOnly` (boolean): Return only the summary header (no steps). Default: false
- `toStep` (integer): End step number (inclusive)

### `agentlens_benchmark` (~431 tokens)

Manage A/B benchmarks: create, list, check status, get results, and control lifecycle.

\**When to use:** To set up controlled experiments comparing different agent configurations (models, prompts, parameters), track which variant performs better, and get statistical results.

\**Workflow:**
1\. `create` — Define a benchmark with 2+ variants and metrics
2\. Tag sessions with variant tags during data collection
3\. `start` — Transition benchmark to running
4\. `status` — Check progress (session counts per variant)
5\. `results` — Get statistical comparison with p-values
6\. `complete` — Finalize the benchmark

\**Actions:**
\- `create`: Set up a new benchmark (name, variants[], metrics[])
\- `list`: List benchmarks, optionally filter by status
\- `status`: Get benchmark detail with per-variant session counts
\- `results`: Get formatted comparison table with statistical analysis
\- `start`: Transition benchmark to running state
\- `complete`: Transition benchmark to completed state

\**Example:** agentlens_benchmark({ action: "create", name: "GPT-4o vs Claude", variants: [{name: "gpt4o", tag: "v-gpt4o"}, {name: "claude", tag: "v-claude"}], metrics: ["cost", "latency", "success_rate"] })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Agent ID to scope the benchmark to
- `benchmarkId` (string): Benchmark ID (required for status/results/start/complete)
- `description` (string): Benchmark description
- `metrics` (array): Metrics to track (e.g., ["cost", "latency", "success_rate"])
- `minSessions` (integer): Minimum sessions per variant before results are meaningful
- `name` (string): Benchmark name (required for create)
- `status` (string): Filter by status (for list action)
- `variants` (array): Variants to compare (required for create, min 2)

### `agentlens_guardrails` (~134 tokens)

Check guardrail status for the current agent. Returns active guardrail rules, their current state, and recent trigger history.

\**When to use:** To check what guardrails are protecting this agent, whether any have been triggered recently, and what conditions/actions are configured.

\**What it returns:** A list of configured guardrail rules with their status (enabled/disabled, trigger count, last trigger time) and recent trigger history.

\**Example:** agentlens_guardrails({}) → returns all guardrail rules and their status.

Input parameters:

- `agentId` (string): Agent ID to check guardrails for (defaults to current agent)

### `agentlens_discover` (~199 tokens)

Discover available agent capabilities in the network.

\**When to use:** Before delegating a task, to find agents that can handle a specific task type. Returns ranked results with trust scores, estimated cost, and latency.

\**Example:** agentlens_discover({ action: "discover", taskType: "code-review", minTrustScore: 70, limit: 5 })

Input parameters:

- `action` (string, required): Operation to perform: discover
- `limit` (number): Max results to return (default: 10, max: 20)
- `maxCost` (number): Maximum estimated cost in USD
- `maxLatency` (number): Maximum estimated latency in milliseconds
- `minTrustScore` (number): Minimum trust score percentile (0-100)
- `taskType` (string, required): Task type to search for (e.g., translation, summarization, code-review, data-extraction, classification, generation, analysis, transformation, custom)

### `agentlens_delegate` (~207 tokens)

Delegate a task to another agent in the AgentLens network.

\**When to use:** When you've discovered an agent capable of handling a specific task (via agentlens_discover) and want to delegate work to it.

\**Example:** agentlens_delegate({ action: "delegate", targetAgentId: "anon-abc123", taskType: "translation", input: { text: "Hello", targetLang: "es" } })

Input parameters:

- `action` (string, required): Operation to perform: delegate
- `fallbackEnabled` (boolean): Enable fallback to alternative agents on failure (default: false)
- `input` (required): Input data for the delegated task
- `maxRetries` (number): Maximum retry attempts with alternative agents (default: 3, max: 10)
- `targetAgentId` (string, required): Anonymous agent ID (from discovery results)
- `taskType` (string, required): Task type to delegate
- `timeoutMs` (number): Timeout in milliseconds (default: 30000)

### `agentlens_sessions` (~248 tokens)

Browse and inspect AgentLens sessions.

\**When to use:** To find past sessions, inspect session details, or view a timeline of events within a session. Useful for debugging, auditing, or reviewing agent activity.

\**Actions:**
\- `list`: List sessions with optional filters (agentId, status, date range, tags)
\- `detail`: Get full session detail with aggregates
\- `timeline`: Get timestamped event list for a session

\**Example:** agentlens_sessions({ action: "list", agentId: "my-agent", status: "completed", limit: 10 })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Filter by agent ID (list)
- `from` (string): Start date ISO (list)
- `limit` (number): Max results, default 20 (list)
- `offset` (number): Pagination offset (list)
- `sessionId` (string): Session ID (required for detail/timeline)
- `status` (string): Filter by status: active, completed, error (list)
- `tags` (array): Filter by tags (list)
- `to` (string): End date ISO (list)

### `agentlens_agents` (~136 tokens)

List, inspect, and manage AgentLens agents.

\**When to use:** To see which agents are registered, check agent details and error rates, or unpause a paused agent.

\**Actions:**
\- `list`: List all agents with error rates
\- `detail`: Get agent detail by ID
\- `unpause`: Clear paused state for an agent

\**Example:** agentlens_agents({ action: "list" })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Agent ID (required for detail/unpause)
- `clearModelOverride` (boolean): Clear model override on unpause

### `agentlens_alerts` (~277 tokens)

Manage alert rules and view alert history.

\**When to use:** To create alerting rules for error rates, costs, or latency thresholds; manage existing rules; or review past alert triggers.

\**Actions:**
\- `list`: List all alert rules
\- `create`: Create a new alert rule
\- `update`: Update an existing alert rule
\- `delete`: Delete an alert rule
\- `history`: View recent alert triggers

\**Example:** agentlens_alerts({ action: "create", name: "High error rate", condition: "error_rate_above", threshold: 0.1, windowMinutes: 60 })

Input parameters:

- `action` (string, required): Action to perform
- `condition` (string): Condition: error_rate_above, cost_above, latency_above (required for create)
- `enabled` (boolean): Enable/disable rule
- `limit` (number): Max history results
- `name` (string): Alert rule name (required for create)
- `notifyChannels` (array): Notification channels
- `ruleId` (string): Rule ID (required for update/delete)
- `scope` (string): Scope: global or agentId
- `threshold` (number): Threshold value (required for create)
- `windowMinutes` (number): Evaluation window in minutes (required for create)

### `agentlens_analytics` (~201 tokens)

Query operational analytics: metrics, costs, agent performance, and tool usage.

\**When to use:** To understand system performance trends, cost breakdowns, agent activity, or tool usage patterns over time.

\**Actions:**
\- `metrics`: Get bucketed metrics with optional range/date filters
\- `costs`: Get cost breakdown
\- `agents`: Get per-agent metrics
\- `tools`: Get tool usage statistics

\**Example:** agentlens_analytics({ action: "metrics", range: "24h" })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Filter by agent ID
- `from` (string): Start date ISO
- `granularity` (string): Bucket granularity
- `range` (string): Shorthand: 1h, 6h, 24h, 3d, 7d, 30d
- `to` (string): End date ISO

### `agentlens_cost_budgets` (~294 tokens)

Manage cost budgets and anomaly detection.

\**When to use:** To create/manage spending limits, check budget utilization, or configure cost anomaly detection.

\**Actions:**
\- `list`: List all cost budgets
\- `create`: Create a new budget
\- `update`: Update an existing budget
\- `delete`: Delete a budget
\- `status`: Check spend vs limit for a budget
\- `anomaly_config`: Get anomaly detection configuration
\- `anomaly_update`: Update anomaly detection settings

\**Example:** agentlens_cost_budgets({ action: "create", scope: "global", period: "daily", limitUsd: 10, onBreach: "alert" })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Agent ID (for agent-scoped budgets)
- `budgetId` (string): Budget ID (required for update/delete/status)
- `downgradeTargetModel` (string): Target model for downgrade action
- `enabled` (boolean): Enable/disable budget
- `limitUsd` (number): Spending limit in USD
- `lookbackDays` (number): Lookback period in days for anomaly detection
- `onBreach` (string): Action on budget breach
- `period` (string): Budget period
- `scope` (string): Budget scope
- `zScoreThreshold` (number): Z-score threshold for anomaly detection

### `agentlens_stats` (~94 tokens)

Get storage statistics and system overview metrics.

\**When to use:** To check database/storage utilization or get a high-level system overview.

\**Actions:**
\- `storage`: Get storage stats (database size, event counts, etc.)
\- `overview`: Get overview metrics (active sessions, agents, recent activity)

\**Example:** agentlens_stats({ action: "storage" })

Input parameters:

- `action` (string, required): Action to perform

### `agentlens_trust` (~103 tokens)

Get trust scores for agents.

\**When to use:** To check the trust/reliability score of an agent before delegating tasks or to monitor agent reputation.

\**Actions:**
\- `score`: Get trust score for a specific agent

\**Example:** agentlens_trust({ action: "score", agentId: "my-agent" })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Agent ID (required for score)

### `agentlens_prompts` (~273 tokens)

Manage prompt templates and versions.

\**Actions:**
\- `list`: List prompt templates (optional category, search filters)
\- `get`: Get a template with all versions by ID
\- `create`: Create a new prompt template with initial content
\- `update`: Create a new version of an existing template
\- `analytics`: Get per-version metrics for a template
\- `fingerprints`: List auto-discovered prompt fingerprints

\**Example:** agentlens_prompts({ action: "list", category: "system" })

Input parameters:

- `action` (string, required): Action to perform
- `agentId` (string): Agent ID filter (for fingerprints)
- `category` (string): Category filter or value
- `changelog` (string): Change description (for update)
- `content` (string): Prompt content (for create, update)
- `description` (string): Template description (for create)
- `from` (string): Start date ISO (for analytics)
- `name` (string): Template name (for create)
- `search` (string): Name search filter (for list)
- `templateId` (string): Template ID (for get, update, analytics)
- `to` (string): End date ISO (for analytics)
- `variables` (string): JSON array of variable definitions (for create)

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/agentkitai-agentlens/agentkitai-agentlens-mcp#diagnostics

## Score history

- 2026-08-03: 67
- 2026-08-02: 69
- 2026-08-01: 33
- 2026-07-31: 18
- 2026-07-30: 25
- 2026-07-28: 43
- 2026-07-27: 43

## Links

- npm package: https://www.npmjs.com/package/@agentkitai/agentlens-mcp
- Socket report: https://socket.dev/npm/package/@agentkitai/agentlens-mcp
- Repository: https://github.com/agentkitai/agentlens
- Changelog RSS feed: https://verifymcp.io/servers/agentkitai-agentlens/agentkitai-agentlens-mcp/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/agentkitai-agentlens/agentkitai-agentlens-mcp/changelog.json
- HTML version of this page: https://verifymcp.io/servers/agentkitai-agentlens/agentkitai-agentlens-mcp