agentic-ledger — Claude Code MCP server: session and cost tracking
A proxy that sits between your agent and the LLM, logs every call, prices it and flags runs that spin in circles. Useful when the bill makes no sense.
claude mcp add agentic-ledger -- uvx agentic-ledgerWhat agentic-ledger does
Agentic Ledger is a transparent proxy in front of your LLM provider. It catches each request and response, tags it with an action_id, writes it down, and passes the upstream answer back untouched. Your agent has no idea it is there.
Records land in SQLite or Postgres, and a live dashboard plus an API sit on top. Start it in the background with agenticledger start — you get the dashboard URL and your terminal back. agenticledger status reports health, agenticledger logs shows activity, agenticledger stop shuts it down. A Docker route exists too, and it needs no Python on the host.
The proxy listens on http://localhost:8000. For Claude one command writes the agent config, with a backup and a merge. Anywhere else you change two things: point base_url at the proxy and send a session ID header so calls group into a single run. Keys, model and messages stay as they are. Postgres and OpenTelemetry come as separate extras, and the Docker image carries SQLite only — for Postgres install the package with pip.
What it helps with
- work out what a run actually cost in tokens and money
- reconstruct the steps an agent took and their order
- catch a run that loops and burns budget
- see calls to different providers in one place
- check your own numbers against the provider invoice
Example prompts for the agent
- Start agentic-ledger and give me the dashboard URL
- What did run
run-1cost, and which steps were in it? - Any stuck loops in the recent runs?
How to install agentic-ledger
Platform CLI
claude mcp add agentic-ledger -- uvx agentic-ledgeruvx runs the command named after the package; if the README names another one, use uvx --from agentic-ledger <command>
Platform CLI
codex mcp add agentic-ledger -- uvx agentic-ledgeruvx runs the command named after the package; if the README names another one, use uvx --from agentic-ledger <command>
Config file
{
"mcpServers": {
"agentic-ledger": {
"command": "uvx",
"args": [
"agentic-ledger"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from agentic-ledger <command>
Config file
{
"servers": {
"agentic-ledger": {
"type": "stdio",
"command": "uvx",
"args": [
"agentic-ledger"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from agentic-ledger <command>
Platform CLI
gemini mcp add agentic-ledger uvx agentic-ledgeruvx runs the command named after the package; if the README names another one, use uvx --from agentic-ledger <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about agentic-ledger
How do I install agentic-ledger in Claude Code?
Run claude mcp add agentic-ledger -- uvx agentic-ledger. Then agenticledger connect claude-code writes the agent config so its calls go through the proxy.
What does agentic-ledger do?
It sits between your agent and the LLM, records requests and responses, prices them, and groups calls into runs by session ID. It also flags runs that get stuck in a loop.
Do I have to change my agent's code?
No. Set base_url to the proxy and add a session ID header. Your API key, model and messages stay the same.
