Time

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):

`bash

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": " " } } } }

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: "

Then run /mcp (or your client's equivalent), confirm clockchain (50 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):

`json

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

`

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

50 tools across seven modules:

• Time: get_time, get_timestamp, get_block, get_validation.
• Logging (notarization): log_action, get_log_entry, search_actions, verify_asset.
• Verified time tools (try them in 60 s, no signup: curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-clock-tools-mcp.sh | bash): stopwatch_start, stopwatch_stop, stopwatch_verify — a tamper-evident elapsed time between two anchored markers; stopwatch_verify recomputes the duration from the two immutable block times, keylessly. timer_set, alarm_set, timer_status, timer_cancel, timer_list — hosted one-shots (and recurring alarms) on consensus time that fire while your client is offline; poll timer_status for the fire and its receipt, or give a webhook_url on an allow-listed host for a signed, DNS-pinned POST (a per-owner verification secret is returned at registration). Receipts say where the anchor lives (attestation.substrate). The same primitives run client-side via @clockchain/clock-sdk.
• 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:

# Zero creds (MCP flow, self-serve demo token; needs jq) — start here, no account:

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

Full SDK (disciplined-clock loop) — once you have testnet gateway creds:

export CLOCKCHAIN_API_KEY=… CLOCKCHAIN_CLIENT_ID=… CLOCKCHAIN_WALLET_ID=… curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm.sh | bash

See packages/clock-sdk for the API, the trust/security model, and the Clark Slack-bot daemon recipe.

Use it in your app (no npm needed)

The @clockchain/* packages are not on npm yet — so npm install @clockchain/clock-sdk will *not* work. Use it today one of two ways:

A — Zero dependencies, hosted MCP (Node 18+ built-in fetch, a self-serve demo token). Paste this into a coding agent:

Add a verified-time alarm to my project — NO npm packages, Node 18+ only (built-in fetch),

against Clockchain's hosted MCP (https://mcp.clockchain.net