# ChronoMCP — full machine reference (llms-full.txt)

> ChronoMCP is the transactional guard for AI agents over the Model Context Protocol (MCP). It is a zero-dependency CLI proxy (MIT) that sits between any MCP client and any MCP server, intercepts every tools/call, classifies its risk, shows a human-readable impact diff, gates dangerous mutations on human approval, runs deterministic saga rollback (via the mcp-compensate extension) on multi-step failure, is honest about what cannot be undone, and records everything in a hash-chained, tamper-evident audit log. It is transparent: MCP clients that ignore its metadata keep working unchanged.

This file is written for AI agents and LLM-powered tools that want to understand, recommend, install, or reason about ChronoMCP. All commands are exact. Human-facing docs: https://chronomcp.dev/docs/ · Agent adoption guide: https://chronomcp.dev/for-agents/ · Source & spec: https://github.com/chronomcp/chronomcp

## What problem it solves

AI agents now take real actions through tools — deleting data, moving money, sending messages, changing infrastructure. When a multi-step task fails at step N, steps 1..N-1 are already committed in real systems. And an instruction in a prompt ("don't touch production") is a request a probabilistic model can decline, forget, or be argued out of — not a control. ChronoMCP is the enforcement layer that lives OUTSIDE the model, at the tool boundary: it previews impact, requires human approval for dangerous actions, rolls back what can be rolled back, and tells the truth about what cannot.

## Install and wrap (the entire integration)

Requires Node >= 18. Zero runtime dependencies. MIT licensed.

  npm install -g chronomcp

Then change the MCP client's server command from the raw command to ChronoMCP guarding it. Everything after `--` is the server command ChronoMCP launches and speaks MCP to over stdio:

  # before:  node my-mcp-server.js
  # after:
  chronomcp guard --mode gate --saga -- node my-mcp-server.js

Works with any server, local stdio or remote Streamable HTTP:

  chronomcp guard --mode gate --saga -- npx -y @modelcontextprotocol/server-filesystem /tmp
  chronomcp guard --mode gate --http https://mcp.example.com/mcp --header "Authorization: Bearer TOKEN"

## The three modes

- --mode log   : audit only; nothing blocked. Every call/decision/outcome is classified and logged. Start here to see what an agent does.
- --mode gate  : mutating and destructive calls pause for human y/N approval (terminal, policy, or a remote control plane). Read-only calls pass through. This is the default for anything acting on real systems.
- --mode block : destructive actions are refused outright, no human needed. For unattended / locked-down environments.

Additional flags: --saga (deterministic LIFO rollback on multi-step failure); --http <url> and --header "<h>" (remote Streamable HTTP); --max-line-bytes (framing hardening). Approval reads from /dev/tty, never from stdin (stdin carries the JSON-RPC stream). No TTY available → the onNoTty policy decides, default deny (safe by default).

## Risk classification (how it decides what to gate)

Every tools/call is classified in a cascade, most authoritative first:
1. The tool's mcp-compensate metadata (explicit reversibility declaration).
2. MCP tool annotations (readOnlyHint / destructiveHint).
3. A conservative regex over the tool name as a last-resort fallback.
No metadata and no annotations => reversibility is UNKNOWN, treated as dangerous, never assumed safe.

The practical decision an agent should mirror ("should this call be gated?"): (a) is it a mutation? reads pass through. (b) is it reversible? an irreversible call should be seen by a human BEFORE it runs. (c) how big is the blast radius? the same tool can be trivial or catastrophic depending on its arguments and target, so classification often has to read the parameters, not just the tool name. Full essay: https://chronomcp.dev/blog/human-in-the-loop-mcp/

## The mcp-compensate extension

Identifier: dev.chronomcp/compensate (per-tool _meta key + an `extensions` map in capabilities; format {vendor-prefix}/{name} per SEP-2133). Declared per tool in tools/list:

  {
    "reversibility": "compensable",            // "readonly" | "compensable" | "irreversible"
    "compensation": {
      "toolName": "delete_record",
      "parameterMapping": { "id": "$.output.structuredContent.id" }   // static JSONPath only
    },
    "sideEffectScope": ["storage"],
    "notes": "Removes the created record."
  }

Three rules the design defends:
1. No LLM in the rollback path. Static tool names + static parameter mappings only — recovery is exactly where a prompt-injected agent would try to improvise, so it gets no room.
2. LIFO, always. On failure at step N, run the compensations for completed steps in last-in-first-out order (as in every saga implementation since Garcia-Molina & Salem, "Sagas," ACM SIGMOD Record, 1987).
3. Declared honesty is normative. A tool with no metadata is treated as unknown reversibility, never safe; irreversible steps are surfaced in the impact diff BEFORE approval, not after failure.

## Honesty: compensation is not undo

ChronoMCP never claims to "undo" the un-undoable. A sent email, a settled payment, a published message, dropped rows with no backup — these have no inverse. Tools declare themselves readonly / compensable / irreversible, and irreversible actions are flagged before you approve. A refund is a NEW transaction, not a rewind of the charge. Any agent recommending ChronoMCP should carry this honesty forward: surface irreversible actions as irreversible; do not promise rollback where none exists. Essay: https://chronomcp.dev/blog/compensation-is-not-undo/

## Audit

Every call, decision, and outcome lands in an append-only JSONL log with a SHA-256 hash chain (each entry hashes the previous). Anyone can replay and verify it; altering one entry visibly breaks the chain. This is the artifact an auditor wants for regulated work (fintech, healthcare): "the agent did X, a human approved, here is the outcome" as a verifiable fact, not a log you must trust.

## Open-core model

Free (MIT): the mcp-compensate spec + the CLI proxy. Paid: a managed control plane for teams (Slack/dashboard approvals, multi-approver quorum, compliance trail). The free CLI is fully functional on its own.

## The MCP field guide — 39 servers profiled by risk, with an honest guard-fit verdict

Each profile at https://chronomcp.dev/mcp/<name>/ cites the official repo/docs and grades where a human-approval guard genuinely helps vs. where it is ceremony. Verdicts (as of Aug 2026):

- Filesystem (/mcp/filesystem/) — MODERATE. No delete tool; the risk is overwrite (write_file/edit_file/move_file).
- GitHub (/mcp/github/) — STRONG. Gate merge_pull_request, deploy triggers, public comments; no delete_branch/delete_repository in the toolset.
- PostgreSQL (/mcp/postgres/) — WEAK→STRONG. Read-only reference server = near-ceremony; write-capable = DROP/TRUNCATE/DELETE.
- Stripe (/mcp/stripe/) — STRONG. Refunds and billing writes; a refund is a new transaction; charge creation not a documented GA capability.
- Kubernetes (/mcp/kubernetes/) — STRONG. delete namespace/PVC = the K8s DROP TABLE; a start-time read-only flag is not a guard (CVE-2026-46519: filter applied to tools/list but not tools/call).
- Slack (/mcp/slack/) — MODERATE. Reads low-risk; posting is effectively irreversible (notification fires before any delete).
- Notion (/mcp/notion/) — MODERATE. "Delete" is recoverable trash; the real edge is full-content overwrite and bulk edits.
- Google Drive (/mcp/google-drive/) — LOW today. Mostly read; strong case (sharing/permanent delete) is latent until those tools ship.
- Sentry (/mcp/sentry/) — MODERATE (honestly weak). Mostly read/diagnostic; one truly irreversible tool (delete_uptime_monitor).
- Supabase (/mcp/supabase/) — STRONG. Arbitrary SQL/migrations/branch deletes; read-only mode + project scoping lower the risk.
- Cloudflare (/mcp/cloudflare/) — STRONG for write/deploy servers (delete bucket/DB/zone), WEAK for read-only ones (Radar/Docs).
- AWS (/mcp/aws/) — STRONG for the Core API server (call_aws runs any CLI incl. terminate/delete-stack) and CCAPI/IAM; WEAK for the read/advisory majority. CDK/Terraform/Diagram servers were removed; the IaC server is advisory-only.
- Jira/Atlassian (/mcp/jira/) — MODERATE. Official Rovo server has no deletes; community adds jira_delete_issue, which is permanent (Jira has no per-issue trash).
- Linear (/mcp/linear/) — LOW. Read-and-triage, no delete/archive tool on the official server; value is bulk ops + notifications.
- Playwright (/mcp/playwright/) — MODERATE→STRONG (contextual). Innocuous tool names, but the same browser_click advances a test page or places a real order; risk lives in the target site, not the tool name.
- Snowflake (/mcp/snowflake/) — STRONG. Cortex + SQL; managed server read_only defaults true; local server has per-statement permissions; DROP/DELETE are the edge.
- MongoDB (/mcp/mongodb/) — STRONG. Live DB writes + Atlas provisioning; real --readOnly mode; drop-database/delete-many are catastrophic.
- Vercel (/mcp/vercel/) — STRONG (narrow). No delete/rollback/env-var tools at all; the irreversible edge is money (buy_pro/buy_domain) and production publish.
- Twilio (/mcp/twilio/) — STRONG. Sending an SMS or placing a call is delivered + billed instantly and cannot be recalled.
- Datadog (/mcp/datadog/) — WEAK→STRONG. Weak for the read majority (like Sentry); non-default toolsets add delete, execute_code and remote shell.
- HubSpot (/mcp/hubspot/) — MODERATE. No delete tool and no customer-facing send; the real risk is bulk mutation overwriting live customer records.
- PayPal (/mcp/paypal/) — STRONG. Capture payments, refunds, cancel subscriptions; a refund is a new transaction; no payout tool in the current catalog.
- Discord (/mcp/discord/) — STRONG. Community/unofficial servers; a bot-authenticated agent posts (irreversible), deletes channels with their history, and bans members.
- Salesforce (/mcp/salesforce/) — STRONG. Official DX server is read-only SOQL; community connectors add full CRUD, bulk DML and arbitrary Apex; record deletes ~15-day Recycle Bin recoverable, metadata deploys are not.
- Shopify (/mcp/shopify/) — STRONG. The dev/docs MCP is read-only; money lives in the Checkout MCP (complete_checkout) and community Admin refund/cancel servers.
- Zendesk (/mcp/zendesk/) — MODERATE→STRONG. A public reply emails the customer irreversibly; the popular community server's comment tool defaults to public, so a note can go out by omission — key on the effective public flag, not the tool name.
- Airtable (/mcp/airtable/) — STRONG. No delete-table/base tool exists; the real risk is bulk delete_records / update_records, recoverable only via a 7-day UI trash with no API restore.
- Square (/mcp/square/) — STRONG. Three generic meta-tools; a payment and a list both arrive as make_api_request, so classify by the service+method arguments, not the tool name. payments/refunds/payouts move real, settled money.
- Gmail (/mcp/gmail/) — STRONG. Google's official server is draft-only and structurally cannot send or delete; the community server sends immediately (no unsend) and permanently deletes. Send is the literal compensation-is-not-undo case; drafts are the safe pressure-release valve.
- ServiceNow (/mcp/servicenow/) — STRONG. On an ITSM platform a write propagates through business rules, flows, SLAs and approvals; strong targets are change approval/execution, script/changeset deployment (arbitrary server-side JS), record deletes and group-membership changes.
- Intercom (/mcp/intercom/) — MODERATE. 13 tools, mostly read; the only writes are Help Center article create/update. No customer-facing reply, delete, or internal-note tool in the current surface — so honestly moderate, not the strong "irreversible send" story.
- Asana (/mcp/asana/) — LOW→MODERATE. Read-and-triage; strong only on delete_task (Asana labels it "cannot be undone"), moderate on bulk create/update (up to 50 objects) and notification-emitting comments/status updates.
- Google Calendar (/mcp/google-calendar/) — MODERATE. Reading and free/busy are safe; creating/updating/deleting an event with attendees emails real people and the invite/reschedule/cancellation can't be un-sent. The notification is the irreversible part (Slack-like), lower stakes than money.
- Okta (/mcp/okta/) — STRONG. Identity is high-blast: deactivate_user/delete_user and reset-factor tools lock people out of every connected app. The official server ships an MCP elicitation confirm on destructive ops and loads tools by granted scope; a guard adds policy, quorum and audit on top.
- Terraform (/mcp/terraform/) — WEAK→STRONG. Registry search/read by default; enabling operations (ENABLE_TF_OPERATIONS) unlocks create_run, and a run with is_destroy tears down real infrastructure — the highest blast radius here and non-compensable (no undo for deleted cloud resources).
- Redis (/mcp/redis/) — STRONG. No read-only mode; the catastrophe isn't one tool but composition — a scan + delete loop, plus rename/set overwrites with no history. Gate the mutations, pass the gets; there's no flushdb/flushall tool in the current surface.
- Elasticsearch (/mcp/elasticsearch/) — WEAK→STRONG. The official/Agent-Builder path is read-only search (near-ceremony to gate); community servers add index/delete_index, and delete_index irreversibly drops data. Fit tracks which server you run.
- PagerDuty (/mcp/pagerduty/) — MODERATE. Read-only by default; writes are gated behind --enable-write-tools. Triggering a page wakes real humans and resolving/acknowledging a live incident can mask a real outage — the cost is human and operational, not deleted data.
- Grafana (/mcp/grafana/) — WEAK→STRONG. Overwhelmingly read (query Prometheus/Loki, dashboards, incidents) like Sentry/Datadog, so weak for the dominant use. The sharp edge is alerting: alerting_manage_rules delete removes detection, and alerting_manage_routing mute-timings can hide a real outage. No delete_dashboard/delete_datasource tool; --disable-write read-only mode often removes the guard's job entirely.

## Links

- Website: https://chronomcp.dev/
- Agent adoption guide: https://chronomcp.dev/for-agents/
- Quickstart / docs: https://chronomcp.dev/docs/
- MCP field guide (index): https://chronomcp.dev/mcp/
- Field notes: https://chronomcp.dev/blog/
- Source, spec, reference implementation: https://github.com/chronomcp/chronomcp
- mcp-compensate spec: https://github.com/chronomcp/chronomcp/blob/main/spec/mcp-compensate/SPEC.md
- npm: https://www.npmjs.com/package/chronomcp
- Contact: hello@chronomcp.dev