The MCP server

Hereling ships a small program your coding assistant can talk to. It sets Hereling up in your project, tells you whether data is arriving, and answers questions about your numbers without you opening the dashboard.

Add it to Claude Code

terminal

claude mcp add hereling -e HERELING_KEY=hl_live_YOUR_MCP_READ_ONLY_KEY -- npx -y hereling

Create an MCP read only key in Settings → Hereling keys and replace the placeholder with it. Run the command once; it is remembered. To take it out again: claude mcp remove hereling.

Your app needs a separate Usage only key for the proxy and usage events. Existing project keys now have Usage only access and cannot call MCP. Create a new MCP key to reconnect your assistant. Keep both keys on trusted servers or in your local MCP configuration; never embed them in browser or mobile apps.

For other MCP clients, run npx -y hereling over stdio with HERELING_KEY in the environment.

The key is the only thing the server sends out, in the x-hereling-key header, to api.hereling.com and nowhere else. Your code stays on your machine.

What you can say to it

Say this	What happens
Set up Hereling in this project	Scans your code and walks you through the changes
Is Hereling receiving my data?	Two lights: AI calls and payment events
Which users are losing me money this month?	The worst offenders, with cost and revenue
What is my most expensive feature over the last 30 days?	Cost per feature, and the model behind it
Put a $1 monthly limit on user abc123	Sets the limit (Pro)
Move user abc123 to a cheaper model	Sets the model switch (Pro)

The four tools

hereling_setup

Connects the app in the current folder. It reads your project's settings from Hereling (which providers are on, your key prefix, your webhook addresses), scans the code for AI calls and payment code, and returns a step-by-step recipe: which files to change, the new addresses, the three headers, where HERELING_KEY goes, which webhook address to paste, which field carries the user id. Your assistant applies the recipe and shows you a diff; the tool itself never touches a file.

The scan reads file paths and line numbers only. No line of code, no key and no prompt leaves your machine. Scripts, tests, docs and experiments are listed separately so the running app comes first.

hereling_verify

Two lights: AI requests and payment events, each with a count and the first and last time one arrived. If a light is red, the answer says what to do next.

hereling_query

Report	Answers
`overview`	Recorded revenue, AI cost, revenue minus AI cost, active users, incomplete conversion counts and unmatched totals
`losing_users`	Users who cost more than they paid, worst first
`expensive_features`	AI cost per feature, with the top model for each
`plan_profit`	Recorded revenue minus AI cost per user for each plan, and budget status
`user`	One end user: totals, per-feature breakdown, active rules

The range is 7 days by default, or 30 days, or the calendar month so far. On the free plan the longer ranges fall back to 7 days and the answer says so.

hereling_act (Pro)

Read-only keys cannot change rules. To enable this tool, explicitly create an MCP management key in Settings → Hereling keys and use it for this MCP connection. Pro is also required. Neither MCP key type can send proxy requests or usage events.

Action	Does
`set_limit`	A monthly USD limit with an explicit Keep running or Strict protection policy
`remove_limit`	Takes the cap off
`set_model`	Switches compatible text requests on a selected provider and API
`remove_model`	Back to the model your app asks for

These are the same rules as the buttons on a user's page, and the proxy checks them on each new admission. On the free plan the tool answers with the upgrade link instead. What the rules actually do to a request is described on the proxy page.

The endpoint behind it

Setup, verification and reports require MCP read only or MCP management access. Rule changes require MCP management. Requests without the required permission return 403 insufficient_key_permissions. Setup never creates webhook endpoints or returns their private addresses. Copy those from the project's Connect page into your payment provider.

The package talks to POST https://api.hereling.com/mcp with the x-hereling-key header and a JSON body { "action": "verify" | "query" | "project" | "act", … }. There is no project id in the request: every answer is scoped to the key's own project. You can call it with curl if you would rather not use MCP at all.

For set_limit, explicitly choose limit_mode: continuity can exceed the limit during concurrent calls, unknown prices or a spend lookup failure; strict reserves capacity first and rejects unsupported requests or unknown costs. Optional max_in_flightis 1–10 (default 2). Strict support is currently limited to fixed OpenAI text snapshots listed in the proxy docs. For set_model, supply model_provider and model_endpoint(chat, responses or messages); incompatible choices are rejected. Old clients that omit these choices must update before changing rules.

Connection limits

The MCP client waits up to 30 seconds for the complete response and never retries automatically. If a rule change times out, check the rule in Hereling before repeating it: the first action may already have completed. Hereling accepts 60 MCP requests per project per 60-second window across all its keys, with a 64 KiB request body limit. HTTP 429 includes Retry-After. See Settings → Connection health for separate key, provider, payment and recording evidence.