korg-ledger — Claude Code MCP server: tamper-evident session ledger
Logs what the agent did into a hash-chained ledger and lets you verify nothing was altered afterward. Useful when you need proof a session ran as recorded.
claude mcp add --env KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> --env KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> --transport stdio korg-ledger -- uvx korgexWhat korg-ledger does
The server exposes korgex tooling over MCP, so an agent can reach the session ledger and you can check its integrity later. A hash chain plus a causal graph tie events together, which is why a single changed character shows up during verification.
It runs through uvx korgex, so there is nothing to install separately. Set KORG_JOURNAL_PATH for the ledger file and KORG_LEDGER_HMAC_KEY for signing. Skip the key and authenticity checking has nothing to compare against.
Setup differs per platform. Claude and Codex take a claude mcp add or codex mcp add line with --env flags. Cursor and GitHub Copilot want a JSON block with command, args and env. Gemini CLI uses gemini mcp add with -e. Copy the whole block for your platform rather than retyping it.
What it helps with
- prove an agent session ledger was not edited after the run
- keep a signed record of agent actions for incident review
- wire the korgex ledger into an agent in Cursor or Claude
- point the ledger at your own directory with a signing key
- check session events against the hash chain and causal graph
Example prompts for the agent
- Connect korg-ledger and show me what is in the current session ledger
- Verify the ledger: the hash chain and causal graph should match
- Set up korg-ledger with
KORG_JOURNAL_PATHandKORG_LEDGER_HMAC_KEY
How to install korg-ledger
Platform CLI
claude mcp add --env KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> --env KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> --transport stdio korg-ledger -- uvx korgexReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>
Platform CLI
codex mcp add korg-ledger --env KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> --env KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> -- uvx korgexReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>
Config file
{
"mcpServers": {
"korg-ledger": {
"command": "uvx",
"args": [
"korgex"
],
"env": {
"KORG_JOURNAL_PATH": "<KORG_JOURNAL_PATH>",
"KORG_LEDGER_HMAC_KEY": "<KORG_LEDGER_HMAC_KEY>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>
Config file
{
"servers": {
"korg-ledger": {
"type": "stdio",
"command": "uvx",
"args": [
"korgex"
],
"env": {
"KORG_JOURNAL_PATH": "<KORG_JOURNAL_PATH>",
"KORG_LEDGER_HMAC_KEY": "<KORG_LEDGER_HMAC_KEY>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <command>
Platform CLI
gemini mcp add -e KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> -e KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> korg-ledger uvx korgexReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from korgex <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 korg-ledger
How do I install korg-ledger in Claude Code?
Add the server with claude mcp add korg-ledger -- uvx korgex. For a ledger path and signing key, use the variant with --env KORG_JOURNAL_PATH=<KORG_JOURNAL_PATH> --env KORG_LEDGER_HMAC_KEY=<KORG_LEDGER_HMAC_KEY> --transport stdio korg-ledger -- uvx korgex.
What does korg-ledger do?
It gives an agent access to the korgex session ledger and lets you confirm the record was not changed. Integrity comes from a hash chain and a causal graph of events.
What do I need to configure for it to work?
Two environment variables: KORG_JOURNAL_PATH for the ledger file and KORG_LEDGER_HMAC_KEY for signing. Both are passed when you add the server.
