Two plugs in, one key out

Margin measures what your agents spend and what it bought. You connect two things, your LLM calls and your evals, and the key that writes them also lets your agents read Margin over MCP.

Last updated 2 November 2026

Before you start

  • Margin is a meter, not a proxy. Your agents call OpenAI, Anthropic and the rest directly; the SDK reads token counts off the response after it returns. We are never in your request path.
  • It is fail-safe. An emit never raises into your request path. Rows are buffered, so ok=True means queued, not stored: a row that fails to land, a bad key included, prints one warning and is counted in delivery_stats() (deliveryStats() in npm).

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.

shell
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:

python
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.

python
meter.record_call(..., verdict="escalate")      # explicit calls
client.chat.completions.create(..., margin_verdict="escalate")  # wrapped clients

If 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:

python
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.

openrouter
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.

http
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.

shell
promptfoo eval -o results.json
margin-meter price results.json

If 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.

python
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 split

You 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:

python
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.

python
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.

http
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:

shell
python -m margin_meter.doctor --json

doctor 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_summaryhow many projects exist, how many emit real economics
margin_portfolio_economicscross-project spend, cost-per-outcome, savings at stake
margin_fix_this_firstthe ranked highest-$-impact opportunities across the estate
margin_list_projectsevery project and its connection state
margin_project_economicsone project: spend, cost-per-outcome, token yield, retry tax
margin_project_money_mapone project's workflows as spend-blocks, with the node-flow
margin_project_recommendationsthe recommendation feed, biggest-$-impact first
margin_activity_logmeasured calls, outcomes and closed-loop actions, in time order
margin_parity_priorfor a task class: how often a cheaper model has held parity
margin_lever_librarythe catalogue of safe-gated optimisation levers
margin_power_projectionthe 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_marginsspend change split into agent headcount vs per-agent intensity
margin_cost_per_outcome_decompositionblended unit-cost change split into within vs between
margin_baumol_assurance_trendthe rework share of unit cost, over time
margin_roi_summarythe parity-gated ROI proof for the estate
margin_flow_roione flow's before-bill, proven route, and counterfactual after-bill
margin_instrument_planthe exact edits to instrument a repo, and the command that verifies them
margin_eval_setup_planthe edits that let Margin run your own eval runner, per setup and live in shadow
margin_stage_planper-STEP model, effort, context, length and retry advice, at the bar your chain length demands
margin_config_half_lifehow fast a tuned config is going obsolete: the half-life of its outcomes-per-dollar
margin_jobsyour project's spend per job over 30 days, with its model and whether an eval covers it
margin_blind_spotswhat your numbers cannot see yet, as counts plus the fix
margin_optimizeevery move Margin can name for your project, ranked by basis; reads only
margin_faceoff_statusyour 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_recommendationpending → approved. Ratifies; enacts nothing.
margin_apply_recommendationadopt a proven route and re-measure before → after.
margin_revert_recommendationback an adopted route out. Requires a reason.
margin_test_moveagent key only: ask Margin to test one listed move on your evals, within the key's spend limit.
margin_my_keysagent key only: this key's limit, what it has reserved, and the keys it handed out.
margin_delegate_keyagent 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.

claude code plugin
# in Claude Code
/plugin marketplace add trymargin/margin-plugins
/plugin install margin@margin
claude code, by hand
// .mcp.json at your repo root
{
  "mcpServers": {
    "margin": {
      "type": "http",
      "url": "https://trymargin.io/api/mcp",
      "headers": { "Authorization": "Bearer ${MARGIN_INGEST_KEY}" }
    }
  }
}
cursor
// .cursor/mcp.json
{
  "mcpServers": {
    "margin": {
      "url": "https://trymargin.io/api/mcp",
      "headers": { "Authorization": "Bearer ${env:MARGIN_INGEST_KEY}" }
    }
  }
}
codex
# ~/.codex/config.toml
[mcp_servers.margin]
url = "https://trymargin.io/api/mcp"
bearer_token_env_var = "MARGIN_INGEST_KEY"
deepseek harness
# ~/.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. StagingA 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 onlyThe 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. ActApply 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.