Docs/Integrations/MCP Server

MCP Server

Optional: query your AI spend and productivity stats from inside your editor.

Not required for GitHub AI tracking

GitHub-based AI detection works automatically via the local proxy or backfill. The MCP server adds productivity session tracking — sessions start when your agent calls any CostLens tool (e.g. checking spend or suggesting a model). It's reactive, not always-on.

What it does

The MCP server gives your coding agent read access to your CostLens data. Ask your agent things like:

"How much have I spent today?"
"What's my productivity this week?"
"Which model is cheapest for this task?"
"Show me my AI ROI summary"

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 start when your agent calls a CostLens tool:

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

A session begins on the first CostLens tool call in a conversation.
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 →