@clocknext/mcp

The ClockNext MCP server — meter usage, verify signals, and manage usage‑based billing directly from AI coding tools (Claude Code, Cursor, Codex, Antigravity, …) and any other Model Context Protocol client.

It runs locally over stdio: your AI tool spawns it as a subprocess, and your organisation's cnk_… API key stays in the server's environment — never in the model's context.

This repo ships two things:

• the MCP server (@clocknext/mcp) — the tools an agent calls.

• the clocknext-onboarding skill — the step‑by‑step playbook that drives a full setup using those tools (human‑in‑the‑loop, sandbox‑first).

Install them together (the Claude Code plugin) or separately. Pick by what you want and which agent you're on:

The skill and the MCP server work together — the skill drives the tools — so for the full guided experience install both (or just use the plugin, which bundles them). The plugin is the one‑command option, but Claude Code only.

A ClockNext API key is required for the tools: Settings → API Keys → cnk_…. It is a server‑side secret — keep it in env/secret config, never in client code or a repo.

1 — The skill (every AI coding agent)

The clocknext-onboarding skill is the guided playbook (detect models → entitlements → plan → meter the codebase → test with a dummy customer). It drives the MCP tools, so install the MCP server too (§2 below) — the skill on its own has nothing to call.

Install it with npx skills — one command, works across Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, VS Code, and ~20 other agents. Target your agent with --agent so it lands where that agent actually looks:

# user-wide (all projects), for a specific agent:
npx skills add ClockNext/clocknext-mcp --global --agent claude-code
# …or this project only:
npx skills add ClockNext/clocknext-mcp --agent claude-code

Swap claude-code for cursor, codex, windsurf, … (or * for every detected agent). npx skills list shows what's installed; npx skills remove clocknext-onboarding removes it. After installing, restart the agent — most load skills at startup.

Claude Code, read this. Claude Code only loads skills from ~/.claude/skills/, .claude/skills/, or a plugin — not the CLI's default universal .agents/skills/ folder. So you must pass --agent claude-code (as above), which installs to ~/.claude/skills/ (with --global) or .claude/skills/. A bare npx skills add … puts it in .agents/skills/, where Claude Code will never see it. Simplest of all for Claude Code: use the plugin — it registers the skill natively and wires the MCP in one step.

Copy the folder from the repo into your agent's skills directory:

git clone https://github.com/ClockNext/clocknext-mcp
# Claude Code — all projects:
mkdir -p ~/.claude/skills && cp -r clocknext-mcp/skills/clocknext-onboarding ~/.claude/skills/
# …or this project only: .claude/skills/

For tools without a native skills folder (Cursor / Windsurf / Codex / Antigravity), point their rules file at skills/clocknext-onboarding/SKILL.md — e.g. .cursor/rules/clocknext-onboarding.md, Windsurf Rules, or AGENTS.md. Keep the references/*.md files alongside SKILL.md.

Related MCP server: Koalr

2 — The MCP server (every AI coding agent)

Gives you the tools the skill (and you) call — one stdio server, npx -y @clocknext/mcp, with your CLOCKNEXT_API_KEY in its env.

Most clients take the standard block below — same JSON, they just differ on the file it goes in:

{
  "mcpServers": {
    "clocknext": {
      "command": "npx",
      "args": ["-y", "@clocknext/mcp"],
      "env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
    }
  }
}

CLI agents

Claude Code — one command:

claude mcp add clocknext --env CLOCKNEXT_API_KEY=cnk_your_key -- npx -y @clocknext/mcp

Gemini CLI — ~/.gemini/settings.json → the standard block.

Codex — ~/.codex/config.toml:

[mcp_servers.clocknext]
command = "npx"
args = ["-y", "@clocknext/mcp"]
env = { CLOCKNEXT_API_KEY = "cnk_your_key" }

GitHub Copilot CLI — copilot mcp add, or ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "clocknext": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@clocknext/mcp"],
      "env": { "CLOCKNEXT_API_KEY": "cnk_your_key" },
      "tools": ["*"]
    }
  }
}

OpenCode — ~/.config/opencode/opencode.json (note: mcp root, command is an array, env is environment):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clocknext": {
      "type": "local",
      "command": ["npx", "-y", "@clocknext/mcp"],
      "environment": { "CLOCKNEXT_API_KEY": "cnk_your_key" },
      "enabled": true
    }
  }
}

Factory (Droid) — droid mcp add, or the standard block in its config with "type": "stdio" added to the server:

droid mcp add --type stdio clocknext "npx -y @clocknext/mcp"

Kimi Code — kimi mcp add clocknext -- npx -y @clocknext/mcp (set CLOCKNEXT_API_KEY in the environment; config lives in ~/.kimi/config.toml).

IDEs

Cursor — .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) → the standard block.

Windsurf — ~/.codeium/windsurf/mcp_config.json → the standard block.

Antigravity — its MCP settings JSON → the standard block.

Kiro — .kiro/settings/mcp.json (project) or ~/.kiro/settings/mcp.json (user) → the standard block. Kiro doesn't inherit your shell PATH, so if npx isn't found, use its full path (which npx).

VS Code (native MCP / Copilot) — .vscode/mcp.json (uses servers, not mcpServers):

{
  "servers": {
    "clocknext": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@clocknext/mcp"],
      "env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
    }
  }
}

Any other MCP client — point it at the stdio command npx -y @clocknext/mcp with CLOCKNEXT_API_KEY in env. @clocknext/mcp is also in the official MCP Registry as io.github.ClockNext/mcp, so registry‑aware clients can discover it directly.

Environment

3 — The Claude Code plugin (Claude Code only)

The one‑command option — installs the MCP server and the clocknext-onboarding skill together, and wires the API key for you. Claude Code only (the plugin format is Claude Code's; other agents use §1 + §2 above).

/plugin marketplace add ClockNext/clocknext-mcp
/plugin install clocknext@clocknext

Claude Code prompts for your ClockNext API key at install (stored securely), runs the bundled server, and auto‑discovers the skill from the plugin's skills/ folder. Verify:

• /mcp → the clocknext tools are listed.

• The skill triggers automatically when you start any ClockNext work (or check your installed skills).

No manual config, no env vars, nothing to build.

Tools

Plus catalogue CRUD (create_plan / create_credit / create_outcome / create_unit …), customer tools (create_customer, create_purchase, bulk_import_customers), and the docs tools (search_docs, get_doc). Run /mcp to see the full list.

A typical agent flow: whoami → list_models → verify_signal (confirm the customer/model/plan price correctly) → record_usage → get_customer_usage (confirm it landed). The clocknext-onboarding skill orchestrates all of this.

Development

npm install          # pulls the published @clocknext/sdk
npm run build        # tsup → dist/index.js (executable bin)
npm run dev          # run from source via tsx
CLOCKNEXT_API_KEY=cnk_... npm start

Built on the official @modelcontextprotocol/sdk over @clocknext/sdk (bundled into dist/ by tsup). stdio today; a hosted Streamable‑HTTP variant is planned. Logs go to stderr (stdout is the protocol channel). The committed dist/ is what the plugin runs — rebuild and commit it on any code change.

Releasing (maintainers) — automated

A tag push publishes both the npm package and the official MCP Registry entry, via .github/workflows/publish-mcp.yml:

# 1. bump the version in package.json, server.json (both "version" fields),
#    src/index.ts and .claude-plugin/plugin.json; rebuild + commit:
npm run build && git commit -am "release: vX.Y.Z"

# 2. tag and push — CI does the rest:
git tag vX.Y.Z && git push origin main --tags

The workflow checks the tag matches package.json, builds, npm publishes (with provenance), then authenticates to the registry with GitHub OIDC (no secret) and publishes server.json. It hosts only metadata pointing at the npm package, so the npm publish runs first.

One‑time setup: add an NPM_TOKEN secret (repo → Settings → Secrets → Actions). To drop the token entirely, configure npm trusted publishing (OIDC) for @clocknext/mcp on npmjs.com and delete the NODE_AUTH_TOKEN line.

npm publish --access public                 # npm first — the registry validates against it
# get the publisher CLI (Linux/macOS, no brew needed):
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github                # device flow — must be a ClockNext org member
./mcp-publisher publish                     # reads server.json (name io.github.ClockNext/mcp)

See the MCP Registry docs.