kepil — Claude Code MCP server: what it does, how to install
Security gate and tamper-evident audit journal for AI agents. Enforces permission mandates and requires human approval for risky steps.
claude mcp add --env KEPIL_DATA=<KEPIL_DATA> --transport stdio kepil -- uvx kepilWhat kepil does
Kepil stands between an AI agent and external infrastructure to evaluate every planned action. The gate checks tasks against an explicit mandate before invoking any model. If a step lacks clear permission, the system triggers a fail-closed refusal. Records stream to an append-only JSONL journal where each entry contains the previous record's hash, making silent log tampering detectable.
The MCP interface exposes seven tools for reviewing agent passports, triggering job steps, and reading order states. A confirmation tool is omitted on purpose: models cannot approve their own irreversible actions. Approvals route exclusively to a human operator via the admin panel at http://localhost:7317 or through Telegram. Pending confirmation cards wait up to 4 hours before alerting the operator again.
When a workflow fails, Kepil walks the dependency tree backwards and executes compensating actions until it encounters an irreversible step. The entire state lives in plain JSON files inside KEPIL_DATA (defaults to ./data), removing any need for external database servers.
What it helps with
- block unauthorized tool invocations before external APIs are hit
- verify audit journal integrity using an append-only hash chain
- route sensitive task sign-offs directly to an operator in Telegram
- replay compensating actions backward to safely undo agent progress
Example prompts for the agent
- Inspect the agent passport and start the next step for ord-0042
- List all pending actions that require human confirmation
- Verify the integrity of the action journal with Kepil
How to install kepil
Platform CLI
claude mcp add --env KEPIL_DATA=<KEPIL_DATA> --transport stdio kepil -- uvx kepilReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>
Platform CLI
codex mcp add kepil --env KEPIL_DATA=<KEPIL_DATA> -- uvx kepilReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>
Config file
{
"mcpServers": {
"kepil": {
"command": "uvx",
"args": [
"kepil"
],
"env": {
"KEPIL_DATA": "<KEPIL_DATA>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>
Config file
{
"servers": {
"kepil": {
"type": "stdio",
"command": "uvx",
"args": [
"kepil"
],
"env": {
"KEPIL_DATA": "<KEPIL_DATA>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <command>
Platform CLI
gemini mcp add -e KEPIL_DATA=<KEPIL_DATA> kepil uvx kepilReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from kepil <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 kepil
How to install kepil in Claude Code?
Run claude mcp add kepil -- uvx kepil. To point the server to a specific data directory, pass the environment flag: claude mcp add --env KEPIL_DATA=<KEPIL_DATA> --transport stdio kepil -- uvx kepil.
What does the kepil MCP server do?
It intercepts agent execution requests, enforces permission boundaries via mandates, and writes an immutable audit trail. Any action marked as irreversible stops until an operator approves it.
Why is there no approval tool in the MCP server?
Kepil leaves out confirmation tools by design so models cannot approve their own tasks. Approvals must come from an actual person through Telegram or the local web UI.
