Integrating with a coding agent

Most R3CKON integrations are now wired in by a coding agent (Claude Code, Cursor, Codex, or similar) rather than typed by hand. This page is written for that arrangement: it tells you, the human, exactly which steps only you can do, and it gives your agent everything else in one block.

Nothing here requires you to be technical. If you can create an account and paste a key into an environment variable, your agent can do the rest.

The three steps only a human can do

1. Create the account. Sign in at r3ckon.com/login with your email. There is no password; a magic link signs you in.
2. Copy your API key. Your admin key (aiok_admin_…) is revealed once at signup. For production code, create an ingest key (aiok_ingest_…) in the console instead: it can push usage but cannot read your account or manage anything.
3. Hand the key to your codebase safely. Put it in your deployment's environment as R3CKON_KEY. Never paste a key into the chat with your agent, never let it be committed, and never put it in client-side code.

Everything else is the agent's job.

The instruction block

Paste this to your agent, in the repository you want wired up:

Integrate R3CKON usage reporting into this codebase.

1. Read https://r3ckon.com/llms-full.txt (the complete documentation)
   before writing any code.
2. Pick the ingestion path using the decision tree at
   https://r3ckon.com/md/agents. Tell me which path you chose and why
   before implementing it.
3. The API key lives in the R3CKON_KEY environment variable. I will set
   it myself: tell me where to set it for this deployment, then treat it
   as opaque. Never print it, log it, or commit it.
4. Implement the path. Reporting must never block or break my AI calls:
   a failed report is dropped, never retried in the request path, and
   never thrown.
5. Verify end to end: send one real usage event (use --dry-run first
   where available), then confirm it landed by calling
   GET https://r3ckon.com/api/admin/overview with the admin key I run
   manually, or by asking me to check the console at r3ckon.com.
6. If you generate any user-facing sustainability copy for this product,
   follow https://r3ckon.com/md/claims exactly. Never write neutrality
   language (neutral-style, net-style, or zero-style status claims, or
   "100% offset"), never use "offset" as a verb, and always present
   estimates as estimates with their range.

The decision tree your agent will use

• The codebase calls a provider SDK directly (OpenAI, Anthropic, or an OpenAI-compatible gateway such as OpenRouter): use @r3ckon/sdk. One install, one wrap of the existing client. Most accurate path: exact cache and reasoning token counts.
• The stack already emits OpenTelemetry GenAI metrics: point an OTLP exporter at /api/v1/otlp/v1/metrics. No code changes.
• Usage happens through a provider account, not this codebase (or the history matters): run the anthropic.mjs or openai.mjs sync script on a schedule. The provider key never leaves your machine; only token counts travel.
• Google Cloud (Vertex): a managed connection with a service account scoped to roles/monitoring.viewer, set up in the console.
• A custom pipeline or internal gateway: POST daily aggregates to the metering API directly.

Paths combine; each source appears separately in the ledger. Full trade-offs are on Connecting usage.

How the agent verifies its work

A finished integration demonstrates all three:

1. A dry run: the sync scripts accept --dry-run and print the exact payload without sending. For SDK integrations, one test call with the reporter's debug logging on.
2. A real event lands: GET /api/admin/overview (admin key) returns the ledger as JSON; the new source and its token counts appear there, and estimation runs as usage arrives, so figures appear without waiting for a close.
3. Failure is safe: kill the network or unset R3CKON_KEY and confirm the application's AI calls still succeed. Reporting is fire-and-forget by design; an integration that can break your product is wrong even if it reports perfectly.

Rules for generated copy

Agents wiring in a sustainability ledger are often asked, in the same session, to write the sustainability page. The claims playbook is the contract for that copy, and the same rules are enforced by the platform on certificate-bearing surfaces. The short form your agent should honor:

• Say what was done, never what it cancels. Activity claims only.
• No neutrality vocabulary: no neutral-style, net-style, or zero-style status claims, and no completeness claims such as "100% offset".
• "Offset" is never a verb, and never describes water or renewable energy instruments.
• Estimates are always presented as estimates, with their 90 percent range and methodology version.
• Retirement statements name the real instrument: project, registry reference, vintage, supplier.

Connect the MCP server

Once wired in, agents can also read the live ledger over MCP: estimates with their ranges, connection health, retirements, certificates, and the exact approved claim sentences (get_claim_language), filled with the account's real figures. The server is read-only by design: no tool can push usage or change the account, which is why the read key is the only key that belongs in a client config.

claude mcp add --transport http r3ckon https://r3ckon.com/api/mcp \
  --header "Authorization: Bearer $R3CKON_READ_KEY"

Generate a read key (aiok_read_…) in the console. Any MCP client works with the equivalent config: URL https://r3ckon.com/api/mcp, header Authorization: Bearer <key>.

Install as a skill

If your agent supports the skills format, the whole procedure above is installable as a skill it will load whenever R3CKON work comes up:

npx skills add TahosaSystems/agent-skills

The skill teaches the same decision tree, verification loop, and copy rules, and pins the documentation URLs, so a fresh session does not need this page pasted in.