Contents
Start here: nothing to install
Sign in, then connect your repository or drop the folder. Margin runs each agent on the evals beside it, in its own sandbox, and reads cost per outcome from that run. You change nothing in your code: a switch arrives as a pull request you merge. The first two runs on a repository are free, and Margin pays up to $100 of the inference. Start at /start.
The two plugs below are optional. Use them when you want Margin to meter your production calls as they happen, or to send outcomes from an eval runner Margin does not run itself.
Plug 1: your calls in
Optional. Install, point it at your deployment, and instrument one workflow. The key comes from /start, issued on the spot.
pip install margin-meter
export MARGIN_INGEST_URL="https://trymargin.io"
export MARGIN_INGEST_KEY="mgk_…"Then wrap the calls in the one workflow you are measuring. instrument_all monkeypatches the installed OpenAI, Anthropic and Gemini SDKs and hooks litellm, so a whole repo is a few lines:
from margin_meter import MarginMeter, instrument_all
meter = MarginMeter() # reads the two env vars above
instrument_all(meter, workflow_id="support-triage")The SDK reads four more things off each call by itself: a hash of the request, a hash and length of its stable prefix (the system prompt, or everything up to your last cache breakpoint), which host served it (OpenRouter names its upstream), and whether the call re-sent a request that was cut off or failed. Hashes and labels only: no prompt or output text leaves your process. The one thing you may add is verdict, a short lowercase label for what the agent decided, which lets Margin tell a repeated check that agreed from one that changed the answer. It is never worked out from the output.
meter.record_call(..., verdict="escalate") # explicit calls
client.chat.completions.create(..., margin_verdict="escalate") # wrapped clientsIf your agents call the API with plain HTTP (urllib, requests, httpx, or OpenRouter directly), there is no SDK for instrument_all to patch. Hand each reply to the meter instead, one line after the call. OpenRouter replies in the OpenAI shape, and its own charge for the call is kept beside the tokens:
reply = json.load(urllib.request.urlopen(req)) # your existing call
meter.record_response(workflow_id="support-triage", response=reply, provider="openai")OpenRouter: add Margin as a Broadcast destination
If your calls go through OpenRouter, you can skip the SDK. In OpenRouter, open Settings → Observability, turn on Broadcast, and add an OpenTelemetry Collector or Webhook destination with this endpoint and header, using your key from /start. Test Connection checks the key and writes nothing.
Endpoint: https://trymargin.io/api/ingest/otlp/v1/traces
Headers: {"Authorization": "Bearer mgk_your_key"}Turn on Cost allocation under Additional generation metadata and each call arrives with what OpenRouter billed for it, which Margin keeps as the cost. Without it, Margin prices the tokens from its own rate table, or marks the call unpriced when it has no rate for that model. A generation is counted once, though OpenRouter repeats it on the root span. Privacy Mode is fine: Margin reads tokens, cost and labels, not prompts. To name the workflow, add workflow_id to the request’s trace object; session_id is kept, and the generation name becomes the step.
A TypeScript SDK has the same shape (npm install margin-meter). Its npm release carries the promptfoo, Braintrust, LangSmith and Vitest adapters; the others below are Python-only. /start walks the setup.
Instrument one workflow, not everything. A workflow with no defined outcome floods the meter with calls that can never resolve to a cost-per-outcome, and the denominator is the whole measurement.
The model is often not the whole bill. If your agent pays per call for a search API, a data vendor or an MCP server, send each charge to /api/ingest/tool-costs with the same key. kind is tool, external_api or mcp, and provenance says how you know the figure: metered from the vendor, customer_supplied (the default) or derived. A sandbox or server bill goes to /api/ingest/infra-costs as a month or day line. Margin adds what you send to the model spend before it divides, and the console names each part. A cost you never send reads “not measured”, never $0.
POST https://trymargin.io/api/ingest/tool-costs
Authorization: Bearer mgk_…
Content-Type: application/json
{"costs": [{"event_id": "run-7:search-3", "workflow_id": "loan-closing",
"session_id": "run-7", "kind": "external_api", "name": "credit-bureau",
"usd": 1.20, "provenance": "metered"}]}Plug 2: your evals in
The outcome is the number everything else divides by, and only you can define it: a merged PR, a passed eval, a resolved ticket. If a harness already grades the workflow, an adapter reads the results file it writes anyway and records one outcome per graded case, pass or fail, with its grading stated.
We divide by the outcomes you define, so if your evals are generic, so is the denominator. The console shows what graded them, and flags a suite that passes or fails nearly every case, because that suite cannot rank two routes.
Adapters ship for promptfoo · Braintrust · LangSmith · Ragas · deepeval · Langfuse · pytest · vitest / jest.
Want a number before you have an account? From 0.6.19, margin-meter price reads a promptfoo result file on your machine and prints cost per passed outcome for each provider in it. It sends nothing and needs no key. It uses only the cost fields promptfoo wrote: a result with no cost is left out and said so, never estimated.
promptfoo eval -o results.json
margin-meter price results.jsonIf your evals are your own script rather than one of those, two calls are enough. Record each graded case with record_case, and read the model from arm(). It returns nothing in production, so your runner behaves exactly as it does today; when Margin compares setups it runs your runner once per setup and hands each run its overrides, with no edit to your code.
from margin_meter import arm, record_case
model = arm().get("model", MY_MODEL) # {} in production; set when Margin tests a setup
...
record_case(meter, suite="triage", case="t12", passed=ok, workflow_id="boss",
agent="ops/boss/boss.py") # which agent ran it: the per-agent cost splitYou do not have to write these by hand. Connect Margin’s MCP server to your coding agent (Claude Code, Cursor) and ask it to set up Margin: the tool margin_eval_setup_plan gives it each edit, where it goes, and a check that proves them, and the agent opens them as one pull request for you to review.
A skipped or errored case is never counted as a verdict, and no adapter adds a harness of ours to your suite. If you have no eval harness, report it directly:
meter.record_outcome(workflow_id="support-triage", passed=True)A check that runs on a schedule and usually finds nothing follows one rule: record one outcome per run, passed=True when the run produced a verdict, including “nothing found”. Record an outcome only when it finds something and cost per outcome becomes spend divided by the rare find. Margin cannot label the unit “per check” until you declare the shape, and nothing takes that declaration today, so state the unit when you quote the number.
meter.record_outcome(workflow_id="price-sheet-check", passed=True) # ran and produced a verdict, even "nothing found"MCP: let your agents query Margin
Margin runs an MCP server over JSON-RPC 2.0. Point any MCP client at it with your ingest key. The key resolves to that project’s own rows, so an agent sees your estate and nobody else’s.
POST https://trymargin.io/api/mcp
Authorization: Bearer mgk_…
Content-Type: application/json
{"jsonrpc":"2.0","id":1,"method":"tools/call",
"params":{"name":"margin_parity_prior",
"arguments":{"task_class":"extraction"}}}GET /api/mcp returns the server descriptor and every tool schema, so a client can discover the surface without credentials.
The one worth building against
margin_parity_prior answers, before an agent spends: for this kind of work, how often has a cheaper model already held outcome parity?
Let a coding agent do the integration
margin_instrument_plan returns the exact edits for your language and the command that verifies them, so Claude Code or Cursor can do install → instrument → verify without you writing any of it. margin_eval_setup_plan does the same for your evals: the two calls that let Margin run your own eval runner once per setup it tests, and, when you want it, shadow testing on real requests. Your agent makes the edits as a pull request; you review and merge.
It does not scan your repository. Margin’s server cannot see your code; the scan runs where the code is:
python -m margin_meter.doctor --jsondoctor is pure stdlib, makes no network call and never imports your modules. It lists every provider call site and whether the meter covers it, fail-closed: a gap it cannot prove covered is reported. It exists because of a real bill where 3 of 6 call sites were unmetered and carried all of the cache-write spend. In Python the plan is one edit at the entrypoint, because instrument_all is global; TypeScript instruments per client, so it touches every file that constructs one.
Read tools
margin_portfolio_summary | how many projects exist, how many emit real economics |
margin_portfolio_economics | cross-project spend, cost-per-outcome, savings at stake |
margin_fix_this_first | the ranked highest-$-impact opportunities across the estate |
margin_list_projects | every project and its connection state |
margin_project_economics | one project: spend, cost-per-outcome, token yield, retry tax |
margin_project_money_map | one project's workflows as spend-blocks, with the node-flow |
margin_project_recommendations | the recommendation feed, biggest-$-impact first |
margin_activity_log | measured calls, outcomes and closed-loop actions, in time order |
margin_parity_prior | for a task class: how often a cheaper model has held parity |
margin_lever_library | the catalogue of safe-gated optimisation levers |
margin_power_projection | the projected date to the parity confidence floor (88 all-passing trials, the Wilson 95% lower-bound sample size, not statistical power) at the current cadence |
margin_agent_margins | spend change split into agent headcount vs per-agent intensity |
margin_cost_per_outcome_decomposition | blended unit-cost change split into within vs between |
margin_baumol_assurance_trend | the rework share of unit cost, over time |
margin_roi_summary | the parity-gated ROI proof for the estate |
margin_flow_roi | one flow's before-bill, proven route, and counterfactual after-bill |
margin_instrument_plan | the exact edits to instrument a repo, and the command that verifies them |
margin_eval_setup_plan | the edits that let Margin run your own eval runner, per setup and live in shadow |
margin_stage_plan | per-STEP model, effort, context, length and retry advice, at the bar your chain length demands |
margin_config_half_life | how fast a tuned config is going obsolete: the half-life of its outcomes-per-dollar |
margin_jobs | your project's spend per job over 30 days, with its model and whether an eval covers it |
margin_blind_spots | what your numbers cannot see yet, as counts plus the fix |
margin_optimize | every move Margin can name for your project, ranked by basis; reads only |
margin_faceoff_status | your latest run, each face-off's verdict, and the watch on merged changes |
Act tools, and why you cannot call them over HTTP
These three close the loop. They are fail-closed over HTTP (GET /api/mcp reports act_enabled: false) and are served only on the local stdio transport with an operator’s sign-off.
margin_approve_recommendation | pending → approved. Ratifies; enacts nothing. |
margin_apply_recommendation | adopt a proven route and re-measure before → after. |
margin_revert_recommendation | back an adopted route out. Requires a reason. |
margin_test_move | agent key only: ask Margin to test one listed move on your evals, within the key's spend limit. |
margin_my_keys | agent key only: this key's limit, what it has reserved, and the keys it handed out. |
margin_delegate_key | agent key allowed to delegate: hand a narrower key with a lower limit to another agent. |
Margin has no mechanism to change your routing at run time. There is no endpoint that tells your code which model to run. We publish a decision, promote, hold or revert, and your code applies it or ignores it. The parity gate and the revert rule are ours; the switch is yours.
In your coding agent
The fastest way is to let the agent do it. Paste this line into Claude Code, Codex or Cursor: Follow https://trymargin.io/mcp-prompt.md to connect Margin to this agent. The file tells it to add Margin to its own client, ask you for the key instead of taking it in chat, and check the tools work. The blocks below are the same setup by hand.
Claude Code, Cursor, Codex and DeepSeek Harness reach the same MCP server. Add one block and your agent can answer “where does the money go”, “what is worth testing” and “what did the face-off find” from your own numbers. Each block reads the key from MARGIN_INGEST_KEY when the agent starts, so the key is never written into the file.
In Claude Code, the quickest way is the plugin from trymargin/margin-plugins. It asks for the key once and keeps it in your system’s credential store, and it adds four skills: connect, costs, check and status.
# in Claude Code
/plugin marketplace add trymargin/margin-plugins
/plugin install margin@margin// .mcp.json at your repo root
{
"mcpServers": {
"margin": {
"type": "http",
"url": "https://trymargin.io/api/mcp",
"headers": { "Authorization": "Bearer ${MARGIN_INGEST_KEY}" }
}
}
}// .cursor/mcp.json
{
"mcpServers": {
"margin": {
"url": "https://trymargin.io/api/mcp",
"headers": { "Authorization": "Bearer ${env:MARGIN_INGEST_KEY}" }
}
}
}# ~/.codex/config.toml
[mcp_servers.margin]
url = "https://trymargin.io/api/mcp"
bearer_token_env_var = "MARGIN_INGEST_KEY"# ~/.dsh/profiles/<profile>/cordis.patch.yml
- insert:
- id: mcp-margin
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: margin
transport: streamable-http
url: https://trymargin.io/api/mcp
headers:
Authorization: !!js '`Bearer ${process.env.MARGIN_INGEST_KEY}`'The four tools written for this are margin_jobs (spend per job), margin_blind_spots, margin_optimize (the moves worth a face-off, each labelled measured, detected, prior or untested) and margin_faceoff_status (verdicts, and the watch on changes you merged). They answer for the one project your key belongs to.
With the ingest key they read; they do not act. That key sits in your code and CI, so it can never spend. To let an agent ask Margin to test a change, create an agent key in the console (Settings, Agent keys) with a spend limit you set, and add a second server at /api/mcp/agent with it. That adds margin_test_move: Margin runs the face-off on your evals and its gate gives the verdict. A key you allow to delegate can hand narrower keys to other agents with margin_delegate_key, each limit carved out of its own. Opening a pull request still happens only in the console, signed in. The figures are what the meter recorded: model calls, plus any tool costs you report. Human time and subscription seats are not in them.
Start in staging. Three rungs, stop at any of them
| 1. Staging | A separate project and key, with environment=staging. Because source is forced server-side to the key’s project, a staging key cannot read or write production rows. Zero production exposure: production is not instrumented yet. |
| 2. Production, meter only | The same SDK with a production key. Still zero production effect: we only record what already happened. Staging traffic is not representative of a bill, so this is where the number becomes real. |
| 3. Act | Apply a published decision in your own code. Nothing moves until you do. |
Before you rely on it
An account starts empty. Signing up is an email: the sign-in link creates the account, and a key is issued on the spot. What it cannot do alone is say what an outcome IS. If you run evals, they are the definition. If you don’t, someone has to agree with you on one before a cost-per-outcome means anything.
No SOC 2 or ISO 27001 report today. We fill security questionnaires on request, and /security lists every field we store.
No value is ever invented. Only you supply one, and it comes from your own records: pushed as value_usd on an outcome, or set as a per-workflow value on your console home. Supply nothing and every figure Margin computes is cost per outcome, labelled as one.
Net value needs the run. To see value per outcome after the AI spend that produced it, send the outcome with link set to session:<your session id>, the same session_id its calls carry. Margin subtracts that session’s metered spend from the value. A session with no metered calls, one with a call it cannot price, or one two workflows share, is left out rather than netted on a partial bill.
A task a person had to finish is not a finished task. Send resolution as escalated_to_human or redone on an outcome that went back to a person, optionally with the human_minutes it took. Margin keeps that run's spend on the bill, takes the task out of the count it divides by, and shows the escalation rate beside cost per outcome. Send nothing and the rate reads “not reported”, never 0%.
The full field list, every column and which ones are free text you choose, is on /security. Questions go to the founder: subh@trymargin.io.