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 set up 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
create customers, plans and purchases that raise real invoices. Keep the key
in env/secret config, prefer a sandbox organisation while you build, and
confirm the plan with get_customer_plan before you subscribe
anyone.
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_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.
The MCP configures billing — it never meters it
There is deliberately no record/track tool. Ingest (POST /api/v1/signal/*) is
asynchronous: it answers 202 {queued, messageId, rawId} and returns no
usage log, and it doesn't validate the agentKey until a worker picks the signal
up. A tool could therefore only ever report "accepted", never "billed" — so
it would report success for a signal that is later thrown away.
Real signals come from your product's own code through
@clocknext/sdk (signals.credit /
.wallet / .outcome), which is also the only thing that proves your
integration works end-to-end. get_customer_usage is the proof a
signal actually landed.
Verify it's connected
A typical agent flow is whoami → list_models → get_customer_plan (confirm
the plan, and that every model and agent key your code sends resolves) → run your
product's own code so it fires a real signal through @clocknext/sdk →
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.