{
  "markdown": "# @clocknext/mcp\n\nThe **ClockNext MCP server** — meter usage, verify signals, and manage\nusage‑based billing directly from AI coding tools (Claude Code, Cursor, Codex,\nAntigravity, …) and any other [Model Context Protocol](https://modelcontextprotocol.io)\nclient.\n\nIt runs **locally over stdio**: your AI tool spawns it as a subprocess, and your\norganisation's `cnk_…` API key stays in the server's environment — never in the\nmodel's context.\n\nThis repo ships **two** things:\n\n- **the MCP server** (`@clocknext/mcp`) — the tools an agent calls.\n- **the `clocknext-onboarding` skill** — the step‑by‑step playbook that drives a\n  full setup using those tools (human‑in‑the‑loop, sandbox‑first).\n\nInstall them together (the Claude Code plugin) or separately. Pick by what you\nwant and which agent you're on:\n\n| Install | What you get | Works in |\n| --- | --- | --- |\n| **[Skill](#1--the-skill-every-ai-coding-agent)** — `npx skills add ClockNext/clocknext-mcp` | the guided onboarding flow | **every** agent (Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, VS Code, …) |\n| **[MCP server](#2--the-mcp-server-every-ai-coding-agent)** — `npx -y @clocknext/mcp` | the tools an agent calls | **every** MCP client |\n| **[Plugin](#3--the-claude-code-plugin-claude-code-only)** — `/plugin install clocknext@clocknext` | MCP tools **+** skill, one step | **Claude Code only** |\n\nThe skill and the MCP server work together — the skill *drives* the tools — so for\nthe full guided experience install **both** (or just use the plugin, which bundles\nthem). The plugin is the one‑command option, but Claude Code only.\n\n> A ClockNext API key is required for the tools: **Settings → API Keys** →\n> `cnk_…`. It is a server‑side secret — keep it in env/secret config, never in\n> client code or a repo.\n\n---\n\n## 1 — The skill (every AI coding agent)\n\nThe **`clocknext-onboarding`** skill is the guided playbook (detect models →\nentitlements → plan → meter the codebase → test with a dummy customer). It\n**drives the MCP tools**, so install the MCP server too (**§2 below**) — the skill\non its own has nothing to call.\n\nInstall it with **[`npx skills`](https://www.skills.sh)** — one command, works\nacross Claude Code, Cursor, Codex, Windsurf, Gemini, Antigravity, VS Code, and\n~20 other agents. **Target your agent with `--agent`** so it lands where that\nagent actually looks:\n\n```bash\n# user-wide (all projects), for a specific agent:\nnpx skills add ClockNext/clocknext-mcp --global --agent claude-code\n# …or this project only:\nnpx skills add ClockNext/clocknext-mcp --agent claude-code\n```\n\nSwap `claude-code` for `cursor`, `codex`, `windsurf`, … (or `*` for every\ndetected agent). `npx skills list` shows what's installed;\n`npx skills remove clocknext-onboarding` removes it. After installing, **restart\nthe agent** — most load skills at startup.\n\n> **Claude Code, read this.** Claude Code only loads skills from\n> `~/.claude/skills/`, `.claude/skills/`, or a plugin — **not** the CLI's default\n> universal `.agents/skills/` folder. So you must pass `--agent claude-code`\n> (as above), which installs to `~/.claude/skills/` (with `--global`) or\n> `.claude/skills/`. A bare `npx skills add …` puts it in `.agents/skills/`, where\n> Claude Code will never see it. Simplest of all for Claude Code: use the\n> [plugin](#3--the-claude-code-plugin-claude-code-only) — it registers the skill\n> natively and wires the MCP in one step.\n\n<details>\n<summary>Manual install (no CLI)</summary>\n\nCopy the folder from the repo into your agent's skills directory:\n\n```bash\ngit clone https://github.com/ClockNext/clocknext-mcp\n# Claude Code — all projects:\nmkdir -p ~/.claude/skills && cp -r clocknext-mcp/skills/clocknext-onboarding ~/.claude/skills/\n# …or this project only: .claude/skills/\n```\n\nFor tools without a native skills folder (Cursor / Windsurf / Codex / Antigravity),\npoint their rules file at `skills/clocknext-onboarding/SKILL.md` — e.g.\n`.cursor/rules/clocknext-onboarding.md`, Windsurf Rules, or `AGENTS.md`. Keep the\n`references/*.md` files alongside `SKILL.md`.\n</details>\n\n---\n\n## 2 — The MCP server (every AI coding agent)\n\nGives you the **tools** the skill (and you) call — one stdio server,\n`npx -y @clocknext/mcp`, with your `CLOCKNEXT_API_KEY` in its env.\n\nMost clients take the **standard block** below — same JSON, they just differ on\nthe file it goes in:\n\n```json\n{\n  \"mcpServers\": {\n    \"clocknext\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@clocknext/mcp\"],\n      \"env\": { \"CLOCKNEXT_API_KEY\": \"cnk_your_key\" }\n    }\n  }\n}\n```\n\n### CLI agents\n\n**Claude Code** — one command:\n\n```bash\nclaude mcp add clocknext --env CLOCKNEXT_API_KEY=cnk_your_key -- npx -y @clocknext/mcp\n```\n\n**Gemini CLI** — `~/.gemini/settings.json` → the **standard block**.\n\n**Codex** — `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.clocknext]\ncommand = \"npx\"\nargs = [\"-y\", \"@clocknext/mcp\"]\nenv = { CLOCKNEXT_API_KEY = \"cnk_your_key\" }\n```\n\n**GitHub Copilot CLI** — `copilot mcp add`, or `~/.copilot/mcp-config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"clocknext\": {\n      \"type\": \"local\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@clocknext/mcp\"],\n      \"env\": { \"CLOCKNEXT_API_KEY\": \"cnk_your_key\" },\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n**OpenCode** — `~/.config/opencode/opencode.json` (note: `mcp` root, `command`\nis an array, env is `environment`):\n\n```json\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"clocknext\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"@clocknext/mcp\"],\n      \"environment\": { \"CLOCKNEXT_API_KEY\": \"cnk_your_key\" },\n      \"enabled\": true\n    }\n  }\n}\n```\n\n**Factory (Droid)** — `droid mcp add`, or the **standard block** in its config\nwith `\"type\": \"stdio\"` added to the server:\n\n```bash\ndroid mcp add --type stdio clocknext \"npx -y @clocknext/mcp\"\n```\n\n**Kimi Code** — `kimi mcp add clocknext -- npx -y @clocknext/mcp` (set\n`CLOCKNEXT_API_KEY` in the environment; config lives in `~/.kimi/config.toml`).\n\n### IDEs\n\n**Cursor** — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global) → the\n**standard block**.\n\n**Windsurf** — `~/.codeium/windsurf/mcp_config.json` → the **standard block**.\n\n**Antigravity** — its MCP settings JSON → the **standard block**.\n\n**Kiro** — `.kiro/settings/mcp.json` (project) or `~/.kiro/settings/mcp.json`\n(user) → the **standard block**. Kiro doesn't inherit your shell `PATH`, so if\n`npx` isn't found, use its full path (`which npx`).\n\n**VS Code** (native MCP / Copilot) — `.vscode/mcp.json` (uses `servers`, not\n`mcpServers`):\n\n```json\n{\n  \"servers\": {\n    \"clocknext\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@clocknext/mcp\"],\n      \"env\": { \"CLOCKNEXT_API_KEY\": \"cnk_your_key\" }\n    }\n  }\n}\n```\n\n**Any other MCP client** — point it at the stdio command `npx -y @clocknext/mcp`\nwith `CLOCKNEXT_API_KEY` in env. `@clocknext/mcp` is also in the official\n[MCP Registry](https://modelcontextprotocol.io/registry/about) as\n`io.github.ClockNext/mcp`, so registry‑aware clients can discover it directly.\n\n### Environment\n\n| Variable | Required | Description |\n| --- | --- | --- |\n| `CLOCKNEXT_API_KEY` | yes | Your org's `cnk_…` key (Settings → API Keys). |\n| `CLOCKNEXT_BASE_URL` | no | Override the API origin (e.g. a staging URL). Defaults to production. |\n| `CLOCKNEXT_DOCS_URL` | no | Override the docs origin for the `search_docs`/`get_doc` tools. Defaults to `https://help.clocknext.com`. |\n\n---\n\n## 3 — The Claude Code plugin (Claude Code only)\n\nThe one‑command option — installs the MCP server **and** the `clocknext-onboarding`\nskill together, and wires the API key for you. **Claude Code only** (the plugin\nformat is Claude Code's; other agents use §1 + §2 above).\n\n```\n/plugin marketplace add ClockNext/clocknext-mcp\n/plugin install clocknext@clocknext\n```\n\nClaude Code prompts for your ClockNext API key at install (stored securely), runs\nthe bundled server, and auto‑discovers the skill from the plugin's `skills/`\nfolder. Verify:\n\n- `/mcp` → the `clocknext` tools are listed.\n- The skill triggers automatically when you start any ClockNext work (or check\n  your installed skills).\n\nNo manual config, no env vars, nothing to build.\n\n---\n\n## Tools\n\n| Tool | What it does |\n| --- | --- |\n| `clocknext_whoami` | Identify the org behind the key and whether it's **sandbox** or **live**. Call first. |\n| `clocknext_list_models` | List enabled models + USD prices per 1M tokens. Use a `modelId` in signals. |\n| `clocknext_add_model` | Enable a catalog model (autopriced); warns if it has no catalog price. |\n| `clocknext_get_customer_usage` | Read back a customer's recent usage logs — confirm a signal landed. |\n| `clocknext_get_customer_balances` | A customer's current wallet / credit / outcome / unit balances. |\n| `clocknext_get_customer_plan` | A customer's current active plan (from their purchase). |\n\nPlus catalogue CRUD (`create_plan` / `create_credit` / `create_outcome` /\n`create_unit` …), customer tools (`create_customer`, `create_purchase`,\n`bulk_import_customers`), and the docs tools (`search_docs`, `get_doc`). Run\n`/mcp` to see the full list.\n\nA typical agent flow: `whoami` → `list_models` → `get_customer_plan` (confirm\nthe plan, and that every model and agent key the code will send resolves) → run\nthe product's own code so it fires a real signal through `@clocknext/sdk` →\n`get_customer_usage` (confirm it landed). The `clocknext-onboarding` skill\norchestrates all of this.\n\n**The MCP configures billing but never meters it.** There is no record/track\ntool by design, and no preview either: real signals come from your product's\ncode via the SDK (`signals.credit` / `.wallet` / `.outcome`), which is also the\nonly thing that proves the integration end-to-end. `get_customer_usage` is the\nproof one landed.\n\n## Development\n\n```bash\nnpm install          # pulls the published @clocknext/sdk\nnpm run build        # tsup → dist/index.js (executable bin)\nnpm run dev          # run from source via tsx\nCLOCKNEXT_API_KEY=cnk_... npm start\n```\n\nBuilt on the official `@modelcontextprotocol/sdk` over `@clocknext/sdk` (bundled\ninto `dist/` by tsup). stdio today; a hosted Streamable‑HTTP variant is planned.\nLogs go to **stderr** (stdout is the protocol channel). The committed `dist/` is\nwhat the plugin runs — rebuild and commit it on any code change.\n\n### Releasing (maintainers) — automated\n\nA tag push publishes **both** the npm package and the official MCP Registry entry,\nvia [`.github/workflows/publish-mcp.yml`](.github/workflows/publish-mcp.yml):\n\n```bash\n# 1. bump the version in package.json, server.json (both \"version\" fields),\n#    src/index.ts and .claude-plugin/plugin.json; rebuild + commit:\nnpm run build && git commit -am \"release: vX.Y.Z\"\n\n# 2. tag and push — CI does the rest:\ngit tag vX.Y.Z && git push origin main --tags\n```\n\nThe workflow checks the tag matches `package.json`, builds, `npm publish`es (with\nprovenance), then authenticates to the registry with **GitHub OIDC** (no secret)\nand publishes `server.json`. It hosts only metadata pointing at the npm package,\nso the npm publish runs first.\n\n**One‑time setup:** add an `NPM_TOKEN` secret (repo → Settings → Secrets → Actions).\nTo drop the token entirely, configure npm **trusted publishing** (OIDC) for\n`@clocknext/mcp` on npmjs.com and delete the `NODE_AUTH_TOKEN` line.\n\n<details>\n<summary>Manual release (no CI)</summary>\n\n```bash\nnpm publish --access public                 # npm first — the registry validates against it\n# get the publisher CLI (Linux/macOS, no brew needed):\ncurl -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\n./mcp-publisher login github                # device flow — must be a ClockNext org member\n./mcp-publisher publish                     # reads server.json (name io.github.ClockNext/mcp)\n```\n</details>\n\nSee the [MCP Registry docs](https://modelcontextprotocol.io/registry/about).\n",
  "bytes": 12004,
  "sha": "244d0258f9919a3e161915f8a0fd228df241544857e80852bf472f39112bb745",
  "repo_slug": "clocknext/clocknext-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_clocknext_mcp_e44a515e/readme"
}