MCP Tools
MCP server
Connect your AI tools to Clocknext using MCP.
The Model Context Protocol (MCP) is a
standard for connecting large language models to platforms like Clocknext. The
Clocknext MCP server runs locally over stdio: your AI tool spawns
@clocknext/mcp as a subprocess, and your organisation's cnk_… API key stays
in the server's environment — never in the model's context. Once connected, your
agent can meter usage, verify signals, and manage usage-based billing on your
behalf.
Connecting an LLM to your billing carries risk
The cnk_… key has organisation-wide read/write access, and the tools can
record real (billed) usage. Keep the key in env/secret config, prefer a
sandbox organisation while you build, and use
verify_signal (a dry run) before recording anything real.
Installation
Most clients take the same standard block — the difference is only the file it goes in:
{
"mcpServers": {
"clocknext": {
"command": "npx",
"args": ["-y", "@clocknext/mcp"],
"env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
}
}
}Choose your client for the exact command or config location:
Configure your MCP client to connect with Clocknext.
One command:
claude mcp add clocknext --env CLOCKNEXT_API_KEY=cnk_your_key -- npx -y @clocknext/mcpThen run /mcp inside Claude Code to confirm the clocknext tools are
connected.
Using another MCP client? Point it at the stdio command npx -y @clocknext/mcp
with CLOCKNEXT_API_KEY in its env. @clocknext/mcp is also in the official
MCP Registry as
io.github.Clocknext/mcp, so registry-aware clients can discover it directly.
Environment
| Variable | Required | Description |
|---|---|---|
CLOCKNEXT_API_KEY | yes | Your org's cnk_… key (Settings → API Keys). |
CLOCKNEXT_BASE_URL | no | Override the API origin (e.g. a staging URL). Defaults to production. |
CLOCKNEXT_DOCS_URL | no | Override the docs origin for the search_docs / get_doc tools. Defaults to https://help.clocknext.com. |
Tools
| Tool | What it does |
|---|---|
clocknext_whoami | Identify the org behind the key and whether it's sandbox or live. Call first. |
clocknext_list_models | List enabled models + USD prices per 1M tokens. Use a modelId in signals. |
clocknext_add_model | Enable a catalog model (autopriced); warns if it has no catalog price. |
clocknext_write_env | Write CLOCKNEXT_API_KEY from the server's own environment into a project's .env — the key still never enters the model's context. Only accepts .env-named files and refuses any file that is git-tracked or not gitignored. |
clocknext_verify_signal | Dry run — validate and price a signal without recording it. Preflight your setup. |
clocknext_record_usage | Record one real (billed) usage signal. Supports an idempotencyKey for safe retries. |
clocknext_get_customer_usage | Read back a customer's recent usage logs — confirm a signal landed. |
clocknext_get_customer_balances | A customer's current wallet / credit / outcome / unit balances. |
clocknext_get_customer_plan | A customer's current active plan (from their purchase). |
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 (or your client's equivalent) to see the full list.
Verify it's connected
A typical agent flow is whoami → list_models → verify_signal (confirm the
customer, model, and plan price correctly) → record_usage →
get_customer_usage (confirm it landed). To check the connection, ask your agent
in natural language — for example: "Use the Clocknext tools to tell me which
organisation my key belongs to and whether it's sandbox or live." It should call
clocknext_whoami and report back.
The clocknext-onboarding skill orchestrates all
of this end-to-end.