Checkpoint

An MCP firewall for IT service-desk agents. Built for the Clocked Build Challenge (building period Oct 21 to Nov 10, 2026).

Checkpoint is an MCP server that sits between an MCP client (Claude Desktop, VS Code, Cursor, MCP Inspector, or a scripted client) and the tools an IT service-desk agent uses: reading inbox messages and tickets, proposing remediation scripts, sending replies. Every tool call passes through Clocked before the agent sees the result or the action happens:

Guard and Inspect are detectors, not enforcement boundaries, and a benign verdict is not execution authorization. Checkpoint keeps least-privilege tool design and human approval in place; Clocked reduces risk, it does not replace those controls.

Status (Oct 21, 2026): all three paths are wired, and four tools work end to end against offline stubs only. No call to Clocked has been made yet because there is no Clocked account or key. The real clients are written against clocked-sdk 0.6.0 and tested against Clocked's recorded docs responses with a fake client, but they have not run against the live API. The hold queue, outbox and simulated run log are in memory. Convex and the dashboard are not started.

What works today

• MCP Streamable HTTP server on a single endpoint, POST/GET/DELETE /mcp, protocol revision 2025-11-25.

  • Origin allowlist: a request whose Origin is not on CHECKPOINT_ALLOWED_ORIGINS gets 403 before any MCP handling. Host is checked against loopback names too (DNS rebinding).

  • Stateful sessions: initialize returns an MCP-Session-Id; other requests without it get 400, unknown or terminated sessions get 404; an unsupported MCP-Protocol-Version gets 400.

• Four tools, over synthetic fixtures (fixtures/inbox.json, fixtures/changes.json; fictional people, example.com):

• Holds are decided by people, not the agent. There is no approve or deny tool. HoldQueue.resolve() exists for the reviewer side (planned: a dashboard) and a decided hold cannot be decided again. Approving a hold does not yet release or replay anything; that comes with the dashboard.

• Inspect policy: deny on verdict malicious or malicious >= threshold; hold on verdict suspicious, suspicious >= 0.5, or high/critical severity; allow only an explicit benign verdict. An unrecognized verdict label is held, never allowed.

• No execution path. Nothing under src/ imports child_process, worker_threads, cluster or vm, or calls eval; a unit test enforces it.

• Offsets are Unicode code points. Clocked counts characters, not UTF-16 units, so Guard cuts, Protect placeholders and Inspect line numbers all go through src/unicode.ts (Array.from), never String.slice on a Clocked offset. Tests cover emoji and astral characters, and rebuilding Protect's replace-style copy from the recorded /pii offsets reproduces Clocked's anonymized_text exactly.

Related MCP server: MCP Warden

Real vs. stub

Guard, Protect and Inspect are each an interface with two implementations:

The stubs are for local tests only. They are not Clocked and not real screening. Every result a stub touches is labeled engine: "offline-stub" and the tool text starts with an UNSCREENED ... OFFLINE STUB ... banner. When a component has neither a key nor its flag, the server refuses to start rather than run unscreened.

Not built yet: Convex audit log, holds table and dashboard; Guard on the user's own request (source: "user"); read_ticket and fetch_kb_page; upstream proxy mode; the evaluation table against live Clocked.

Quick start

Requires Node.js 20+ (developed on 26) and gitleaks for commits.

git config core.hooksPath .githooks   # secret scan on every commit (see below)
npm ci
npm run check                          # typecheck + unit tests + smoke test (offline stub, no network)

# Run the server locally without Clocked (offline stubs, for development only):
CHECKPOINT_GUARD=offline-stub CHECKPOINT_PROTECT=offline-stub CHECKPOINT_INSPECT=offline-stub npm start

# With Clocked (once you have a key): copy .env.example to .env, set CLOCKED_API_KEY, then
node --env-file=.env --import tsx src/main.ts

The server listens on http://127.0.0.1:3333/mcp. Point any Streamable HTTP MCP client (for example MCP Inspector) at it.

Pinned dependencies

All versions are exact (save-exact), and package-lock.json is committed.

Fixtures

• fixtures/docs/: request bodies and recorded responses from Clocked's public docs (Guard, Protect, Inspect examples).

• fixtures/recorded/: our own raw responses, written by scripts/record-clocked.mjs (empty until a key exists).

• fixtures/inbox.json: synthetic inbox. One message carries an obvious prompt-injection payload surrounded by emoji and astral letters; one carries personal data (email, employee id, IP, phone) for Protect.

• fixtures/changes.json: synthetic approved change tickets whose scope Inspect assesses scripts against. CHG-DEMO-204 reuses the scope from Clocked's /script docs example.

Secret scanning (do this first)

Commits are scanned by gitleaks through a versioned hook in .githooks/pre-commit. After cloning:

# 1. Install gitleaks >= 8.19 (see the gitleaks README), then:
git config core.hooksPath .githooks

The hook refuses to commit if gitleaks is missing. .gitleaks.toml extends the default rules with one for Clocked keys (clk_...). Keep keys in .env (gitignored); .env.example lists the variable names only.

License

MIT, see LICENSE.