Docs/Integrations/MCP Server

MCP Server

AI productivity tracking and cost management for coding agents.

What it does

The CostLens MCP server sits inside your coding agent and passively tracks what AI actually ships. No manual reporting, no behavior change required.

Automatic session tracking (start, end, duration)
Event logging (commits, PRs, deploys, file edits)
Cost tracking per session and per deliverable
Heartbeat system (detects abandoned sessions)
Real-time spend summary
Prompt complexity classification

Quick Start (30 seconds)

One command to authenticate and configure your agent:

npx @costlens/mcp-server setup

This opens your browser to authenticate, saves your key locally, and auto-configures any detected agent (Kiro, Cursor, Claude Code).

CLI commands:

npx @costlens/mcp-server setupAuthenticate + configure agent + hooksnpx @costlens/mcp-server doctorCheck everything is workingnpx @costlens/mcp-server statusCheck connection + spendnpx @costlens/mcp-server hooksReinstall git hooksnpx @costlens/mcp-server loginRe-authenticate

Manual Setup

If you prefer to configure manually, add to your agent's MCP config. Get your key from Settings → MCP Keys.

Kiro

~/.kiro/settings/mcp.json

{
  "mcpServers": {
    "costlens": {
      "command": "npx",
      "args": ["-y", "@costlens/mcp-server"],
      "env": {
        "COSTLENS_MCP_KEY": "mcp_your_key_here"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "costlens": {
      "command": "npx",
      "args": ["-y", "@costlens/mcp-server"],
      "env": {
        "COSTLENS_MCP_KEY": "mcp_your_key_here"
      }
    }
  }
}

Claude Code

~/.claude/mcp_servers.json

{
  "mcpServers": {
    "costlens": {
      "command": "npx",
      "args": ["-y", "@costlens/mcp-server"],
      "env": {
        "COSTLENS_MCP_KEY": "mcp_your_key_here"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "mcpServers": {
    "costlens": {
      "command": "npx",
      "args": ["-y", "@costlens/mcp-server"],
      "env": {
        "COSTLENS_MCP_KEY": "mcp_your_key_here"
      }
    }
  }
}

Available Tools

Tool	Description
start_session	Start tracking a coding session
end_session	End session with outcome and artifacts
log_event	Log a meaningful action (commit, PR, deploy)
get_productivity_summary	Get productivity metrics for a period
get_spend_summary	Get current spend (daily, weekly, monthly)
costlens_suggest_model	Get cost-optimized model suggestion
get_github_metrics	PRs merged, review rounds, first-pass rate, cost per PR

How Sessions Work

Sessions are tracked automatically:

start_session — called when agent begins a task. Returns a session ID.
Heartbeat — MCP sends a ping every 60 seconds to keep the session alive.
log_event — fired on meaningful actions (commits, PRs, file edits).
end_session — called when task completes. Records outcome and artifacts.

If the agent crashes or terminal closes, the heartbeat stops. After 5 minutes with no heartbeat, the session is automatically marked as abandoned.

Tracking Modes

Each API key has a tracking mode, configurable from Settings → API Keys. This controls how the MCP server tracks sessions.

Mode	Behavior
manual	Default. Agent must explicitly call start_session, end_session, and log_event.
auto	MCP auto-starts a session on first tool call, auto-logs prompt events, auto-ends on shutdown.

Auto mode details

Session starts automatically on the first tool call (no need to call start_session)
Every costlens_suggest_model call logs a prompt event with complexity metadata
Heartbeat runs every 60 seconds
On process exit, session closes with outcome "completed" and total tool call count

Privacy

Auto mode does not change what data is sent. Prompt text never leaves your machine. Only metadata is synced: complexity level, model names, provider, and tool call counts.

Event Types

// log_event accepts these event types:
{
  "session_id": "uuid",
  "event_type": "prompt | commit | pr_created | deploy | file_edit | test_run",
  "metadata": {
    "model": "claude-sonnet-4.6",
    "tokens_in": 1200,
    "tokens_out": 3400,
    "cost": 0.0045,
    "files_changed": 3
  }
}

Environment Variables

Variable	Description
COSTLENS_MCP_KEY	Your MCP key (from Settings → MCP Keys)
COSTLENS_API_URL	API base URL (default: https://api.costlens.dev)

Zero Latency

CostLens adds zero latency to your workflow. All tracking is async and non-blocking. The MCP server never sits between your prompt and the LLM response.

← Anthropic

Slack →