Clockchain Developer Tools

A CLI and an MCP server that add Clockchain's tools — consensus time, notarization, smart-contract scheduling, audit trails, and agent identity verification — to any MCP client (Claude Code, Cursor, Claude Desktop, Codex, Hermes, OpenClaw, …) and your terminal. It wraps the live D4 node gateway at node.clockchain.network; it does not change the blockchain protocol.

Fastest path — verified-time alarm, no account, one command (for agents & humans):

Terminal

Copy

curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm-mcp.sh | bash

(requires jq; mints a free demo token, no signup — anchors a fire and keyless-verifies it through the hosted MCP.) Safe to run unattended: no account, no API key, no secrets — it spends only one log credit on a shared demo account (nothing of yours). An agent can run this directly without approval. Typical run ≈ 30 s (the alarm wait); set CC_WAIT_S=5 to shorten.

Install it in your MCP client: INSTALL.md — hosted endpoint (any client, recommended) or self-host (local stdio). Non-engineer? Try it in ~10 min: TRY-IT.md · Engineers: QUICKSTART.md Agent? Load the playbook: skills/clockchain-verified-alarm/SKILL.md — the verified-time invariants, so you use the tools right the first time. Roadmap + current limitations: roadmap.md

Quick install — hosted endpoint (any MCP client)

Works with any MCP client — Claude Code, Cursor, Claude Desktop, Codex, Hermes, OpenClaw. Get a testnet token (x-api-key) instantly — curl -X POST https://mcp.clockchain.network/token (no signup) — then add this to your client's MCP config:

{
  "mcpServers": {
    "clockchain": {
      "type": "http",
      "url": "https://mcp.clockchain.network/mcp",
      "headers": { "x-api-key": "<YOUR_TOKEN>" }
    }
  }
}

Zero-creds alarm demo (no account, no build — requires jq): curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm-mcp.sh | bash

CLI with an mcp add command (Claude Code shown):

claude mcp add clockchain --transport http https://mcp.clockchain.network/mcp \
  --header "x-api-key: <YOUR_TOKEN>"

Then run /mcp (or your client's equivalent), confirm clockchain (31 tools), and ask: "use clockchain to get the current consensus time." Self-host (local stdio), bring-your-own-key, and chat-connector setup are in INSTALL.md.

Ask an agent to connect it — no install

No machine to set up? Hand any MCP-capable agent (Claude Code, Cursor, Codex, Hermes, OpenClaw, Claude Desktop) the prompt below — the server is already hosted, so there's nothing to clone or build:

I want to use the Clockchain MCP server. It's already hosted, so do NOT clone or build any repo — just connect to the remote server over HTTP. Add an MCP server named clockchain with this config (substitute my token):

config.json

Copy

{ "mcpServers": { "clockchain": { "type": "http", "url": "https://mcp.clockchain.network/mcp", "headers": { "x-api-key": "<YOUR_TOKEN>" } } } }

Then list your MCP servers to confirm clockchain is connected, and call its get_time tool to show me the current Clockchain consensus time.

Ask the team for a per-user token — the Clockchain key stays on the server. The same hosted endpoint (https://mcp.clockchain.network/mcp) works from any MCP client. Chat-connector clients (claude.ai chat, Cowork) are different — see INSTALL.md.

What you get

31 tools across six modules:

• Time: get_time, get_timestamp, get_block, get_validation.
• Logging (notarization): log_action, get_log_entry, search_actions, verify_asset.
• Scheduler (smart-contract): get_contract_types, estimate_schedule, create_schedule, list_schedules. Types/estimate/list are live; create_schedule is a preview — it's blocked on the backend signing-message spec. Scheduling is non-custodial: the caller's own EVM wallet signs, the server never fabricates a signature.
• Audit (derivative — composes Time + Logging + Identity, no new primitive): generate_audit_trail, generate_compliance_report (EU AI Act Art. 12 / SEC 17a-4 / ISO 27001 presets), build_evidence_package, verify_package.
• Agent identity (verification, valid-at-T — not authentication): resolve_agent, attest_action, complete_attestation, verify_receipt, mint_identity, revoke_identity, delegate_authority, get_identity_history, verify_identity_at, verify_cross_party. attest_action with wait=false submits without blocking; complete_attestation is the poll that returns the confirmed receipt once the block lands.
• Commitments (TSA): tsa_issue, tsa_checkpoint, tsa_attest, tsa_settle, tsa_status. A commitment lifecycle on the anchor primitives — issue → checkpoint → attest (kept/broken) → settle, plus status. tsa_attest reconciles the on-chain anchor time vs the deadline into a kept/broken-late/ broken verdict; the consequence is recorded, not enforced (MVP).

Cross-party verification is live and keyless: GET /searchAssetFromChain?blockHeight={h} reads the immutable on-chain block with no API key. That block — not the mutable /ledger/{id} cache — is the authoritative record; verification resolves to the chain.

Packages (this monorepo):

⏰ Alarms & timers run in a client-side component — by design

The MCP server provides the trust primitives — consensus time, tamper-evident notarization, attest_action, and keyless on-chain verification. Stopwatch (provable elapsed time) works directly through these tools. Alarm and Timer — anything that auto-fires at a future time — additionally require the client-side companion @clockchain/clock-sdk.

This split is deliberate, and is a trust property rather than a limitation: your schedule and the actions you fire stay inside your environment. Clockchain never holds your schedule, never holds your keys, and never acts on your behalf — it supplies only neutral, verifiable time and an immutable, independently-verifiable record of each fire. A blockchain cannot (and, for neutrality, should not) reach out to wake your systems; the companion disciplines a local clock to Clockchain (NTP-style) and fires within your trust boundary, anchoring a keyless-verifiable receipt.

No SDK, no creds — just want to SEE it work? Run the alarm flow demo: bash packages/clock-sdk/examples/try-alarm-mcp.sh (or the curl one-liner at the top). It mints a free demo token and runs the full anchor + keyless-verify cycle (log_action polling on the hosted MCP — no SDK build). That shows the trust primitives firing; it is not the client-side scheduler. To actually run a real client-side alarm, the SDK path below adds the disciplined-clock sync + the ClockScheduler class — the true auto-firing Alarm inside your trust boundary. In short: the MCP flow is the no-creds way to see an anchored fire; the SDK is the way to operate a real alarm.

Install + operate: packages/clock-sdk — quickstart, the trust/security model, and a production daemon recipe (runs under pm2).

Managed option (roadmap): an optional hosted keeper, exposed via MCP schedule_trigger tools, will fire server-side for teams that prefer not to run the companion — with the same verifiable receipts. See roadmap.md.

A @clockchain/cli for the terminal is planned — see roadmap.md.

Verified-time alarms (clock-sdk)

Fire on Clockchain's neutral, verifiable clock — and prove every fire. @clockchain/clock-sdk is a client-side disciplined clock + scheduler: Alarm, Timer, Stopwatch. The chain stays a pure clock + notary; scheduling runs in your process, and each fire is anchored to a keyless-verifiable receipt.

How it works: sync to Clockchain NTP-style (offset + uncertainty — not polling, not a beacon) → fire locally when clockchain_now ≥ T → anchor the fire (attest_action) → keyless-verify against the immutable on-chain block. Works with or without a future signed time beacon (pluggable time source). Something must be running to fire at T, so it lives client-side (e.g. on an always-on host) — a blockchain can't wake your client.

Status — PoC, verified live. Built + merged (35 unit tests; four scheduler bugs fixed 2026-06). Measured end-to-end: clock read ≈0.12 s, fire → anchored on-chain ≈1.4 s (well under a 3 s budget), then verify_cross_party → verifiedAgainst: "on-chain block", keyless: true. (That 1.4 s is fire→anchored; the wait until the fire is the delay you schedule — your fireAt / CC_WAIT_S — not SDK overhead, so total wall-clock = your wait + ~1.4 s.) Audit / SLA / agent-deadline tier — not microsecond / HFT. Single-validator testnet, so "court-grade" is a target, not a present claim.

Try it: