Clockchain MCP server

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

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

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

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

Package	What it is
@clockchain/mcp-server	The MCP server — clockchain-mcp (dist/stdio.js), stdio + HTTP transports.
@clockchain/core	Shared client, types, hashing/receipt + ERC-8004 helpers (Node-only, no extra deps).
@clockchain/web-demo	Browser chat demo — an LLM agent driving the tools over MCP.
@clockchain/clock-sdk	Client-side verified-time primitives — disciplined clock + alarm/timer scheduler + stopwatch. Required to operate alarms/timers (see callout below).

⏰ 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.network/mcp — JSON-RPC over HTTP, SSE replies).

1. Key:  curl -X POST https://mcp.clockchain.network/token  -> demo token (no signup); use as
   header x-api-key. Mint ONCE and cache — it's IP-rate-limited.
2. call(name,args) helper: POST {jsonrpc:"2.0",id:1,method:"tools/call",params:{name,arguments:args}}
   with headers x-api-key + accept "application/json, text/event-stream". Reply is SSE — take the
   last `data:` line, JSON-parse, read result.content[0].text (itself a JSON string).
3. Alarm: poll get_timestamp (madMarzulloTime, ISO 8601 since 2026-09; older gateways used
   DD-MM-YYYY_HH:MM:SS:mmm — parse both) until consensus
   time >= your target T (never fire early), then log_action {action, asset_reference_id, content,
   wait:true, wait_ms:30000} to fire + anchor. Content is SHA-256-hashed, never stored.
4. Assert it anchored: if blockHeight is null the validator pool was degraded — treat as FAILURE,
   don't claim success.
5. Verify keylessly: verify_cross_party {ledger_id, block_height:<number>} — result nests under
   .onChain; expect verifiedAgainst "on-chain block", keyless true.

Report the fired time, blockHeight, and verify result.

B — The SDK classes (disciplined clock + scheduler) — clone the monorepo and build, then import the workspace packages (npm linking, no registry):

git clone --depth 1 https://github.com/thetangstr/clockchain-developer-tools.git
cd clockchain-developer-tools && npm install && npm run build
# then import @clockchain/clock-sdk / @clockchain/core from within the workspace,
# or copy packages/clock-sdk/examples/alarm-live.mjs as a starting point.

npm install @clockchain/clock-sdk @clockchain/core will work once the packages are published — see roadmap.md.

Roadmap

Phase	Scope	Status
0 · Relabel + docs	Clarify create_schedule is a contract deploy, not an alarm; ship docs	✅ done
1 · Client SDK	Disciplined clock + scheduler (Alarm / Timer / Stopwatch) + examples	✅ built + merged; PoC verified live
2 · Hosted keeper	Off-chain dispatch behind MCP schedule_trigger tools — zero-install, fire-while-offline; reliable delivery (retries / idempotency / DLQ)	◻ next (on demand)
3 · Multi-validator	Unlocks the court-grade claim	◻ gated (protocol roadmap)

Reliability gate: a fire must actually anchor — a degraded validator pool can leave a receipt cache-only (blockHeight null). Tracked as P0 (don't report success until anchored); multi-validator (Phase 3) addresses pool participation. The try-alarm-mcp.sh script auto-detects this and handles it — no manual step needed.

Status

Working against the live gateway. The MCP server is verified working — initialize + tools/list returns 50 tools and live calls succeed. Verified surface (updated 2026-06-11):

• Time: read consensus time from the public /getTime (no key scope). The /api/time/* family 401s on logging-scope keys.
• Notarization: /log, /ledger/{id}, /searchAsset, /getValidationBlock all confirmed working — log, confirm on-chain, retrieve, verify.
• Cross-party verification: live and keyless — GET /searchAssetFromChain?blockHeight={h} reads the immutable on-chain block with no API key, and that block is the authoritative record.
• Smart-contract scheduling: contract types, estimate, and list are live; create_schedule is a preview, blocked on the backend signing-message spec. Signature-based and non-custodial (the caller's EVM wallet signs).
• Agent identity: verification (valid-at-T), not authentication. The ERC-8004 registry is live and resolving; identity-graph writes (mint/revoke/delegate) resolve against a directory that is still preview.
• Designed for court-grade evidence. Single-validator testnet; tight rate limits.

Full current limitations + roadmap: roadmap.md.

Hosting, CI/CD & ops

Hosted on GCP Cloud Run at https://mcp.clockchain.network/mcp (token-gated + bring-your-own-key), auto-deployed on push to main behind a test gate.

File	What it is
CLOUD-RUN.md	Deploy + ops runbook: keyless WIF CI/CD, Cloud Armor, monitoring, secret/token rotation, rollback. Canonical hosting doc.
cicd-plan.md	CI/CD pipeline, non-negotiable rules, and forward plan.
AGENTS.md	Contributor/agent guide — run tests before push, never bypass the deploy gate, one agent per worktree.
auth-and-traffic-decision.md	Single-ID front door, delegated vs BYO, Cowork vs Claude Code, channel/traffic + cost model.
agentdash-mcp-integration-brief.md	Hand-off brief for the AgentDash team to integrate the hosted MCP.
eval/	Execution-scored eval harness — Layer-A perf + Layer-B agent task suite (on-chain checks, no LLM judge).
RETRO-2026-06-13.md	Retro of the 06-11 → 06-13 build (Cloud Run, CI/CD, TSA, eval).

DELEGATED-ACCESS.md below describes the retired Mac-mini path — superseded by CLOUD-RUN.md.

Specs & planning docs

Background, design decisions, and rollout plans (this repo started as the planning surface for the work, and those docs still live here):

File	What it is	Audience
mcp-deployment-brief.md	Start here for approval. One-page brief: requirements + deployment dependencies + network-exposure model, with sign-off blocks for stakeholders, network team, and backend.	Stakeholders / Network / Backend
DELEGATED-ACCESS.md	Give testers access without the API key or a VPN: Cloudflare Access in front of the web demo + MCP endpoint, with token/rate/budget caps.	Engineering / ops
implementation-plan.md	Full technical spec and build plan. Source of truth.	Engineering
implementation-plan-technical.html	Slide version of the spec, with the design detail.	Engineering review
implementation-plan.html	Short, high-level overview deck.	Business / stakeholders
product-findings.md	Hands-on findings from the live network + dashboard.	Product / engineering
industry-landscape.md	Evidence on what leading timestamping/provenance platforms do, and where Clockchain can differentiate.	Product / strategy
mcp-readiness.md	Per-tool assessment of which APIs are ready to become MCP tools for Products A & B, grounded in live tests.	Engineering / product
journeys.md	Developer and agent end-to-end journeys, marking where the current API flow supports or breaks autonomous agent usage.	Engineering / product
product-a-identity-decision.md	Decision memo: proprietary DID vs ERC-8004 + SIWA for agent identity. Recommends a hybrid — adopt the standard, differentiate on time/validation.	Product / leadership
deployment.md	Hosting plan: local stdio (devs), Mac mini test host (business users + AgentDash), and the AWS production plan + info checklist.	Engineering / ops
poc-build-plan.md	Goal + sequenced plan to get the MCP server running on the Mac mini (and how it connects to Clockchain).	Engineering / leadership
roadmap.md	Current roadmap, what works, and known limitations.	Product / engineering

Open either .html file in a browser to present (arrow keys to navigate, Esc for the slide overview).