Skip to main content

​
Core Concepts

MarginFront watches what your AI agents do, tracks what it costs you, and bills your customers. That’s it. Everything below is just naming the moving parts.

​
The building blocks

​
1. Agent

Your AI product. The thing that does work for your customers. A customer support bot is one agent. A research assistant is another. A document analyzer is a third. If you only sell one product, you have one agent. If you sell three products that price differently, you have three agents. Each agent has a code (a short handle you pick, like cs-bot or research-v2). You use this code when logging usage events — it tells MarginFront which product did the work. You create agents in the dashboard.

​
2. Customer

Who you’re billing. One of YOUR end users or companies. Each customer has an externalId — the user ID from your own system (like acme-001 or user_847). This is how MarginFront connects usage events to the right customer without you having to memorize MarginFront’s internal UUIDs. You can create customers through the dashboard, the API, the SDK, or the MCP tool.

​
3. Signal

What you measure. A deliverable or outcome your agent produces. Good signals (things your customer cares about):
  • messages — messages sent by a chatbot
  • reports-generated — full reports produced
  • pages-processed — document pages analyzed
Bad signals (internal details your customer doesn’t care about):
  • gpt-4o-call — that’s an internal cost, not a deliverable
  • api-requests — too technical, doesn’t map to value
Signals are what customers see on their invoices. They’re the answer to “what am I paying for?” You create signals in the dashboard, and each signal belongs to one agent.

​
4. Event

A record that something happened. This is the core data type — everything else is built from events. An event says: “Agent cs-bot sent 1 message for customer acme-001 using gpt-4o from openai, consuming 523 input tokens and 117 output tokens.” You log events by calling POST /v1/usage/record (or mf.usage.record() with the SDK). This is the endpoint your code calls all day, every day once you’re live. Everything else — costs, revenue, invoices, margins — is calculated from these events.

​
5. Service Costs

Calculated automatically. You don’t set these. When you log an event with a model and provider (like gpt-4o from openai), MarginFront looks up the token pricing in its built-in table of 300+ LLM models. It multiplies your input tokens by the input price, your output tokens by the output price, and stores the result as the service cost for that event. Your customers never see service costs. They’re for YOUR margin dashboard — so you can answer “how much did it actually cost me to serve this customer this month?” If MarginFront doesn’t recognize the model you sent, the event still saves — but with cost = null (not zero, not dropped). You can map the unknown model to a known one in the dashboard, and MarginFront backfills the cost retroactively. Events are never thrown away.

​
6. Pricing Plan

Turns your costs into prices. This is where you decide what to charge. A pricing plan sets the rate per unit of each signal. “I charge 0.10permessage"or"0.10 per message" or "2.00 per report.” Think of it like the “Starter Plan” or “Pro Plan” you’d show on your pricing page. Created in the dashboard, tied to an agent.

​
7. Subscription

Ties a customer to an agent through a pricing plan. “Starting April 1, bill Acme Inc for the cs-bot using the Starter Plan, on a monthly billing cycle.” Without a subscription, MarginFront still tracks costs (what things cost you), but it can’t calculate revenue (what you charge the customer) or generate invoices.

​
8. Invoice

Auto-generated at the end of each billing cycle from a subscription’s usage. Shows line items per signal with quantity and price. Example: “Messages: 150 x 0.10=0.10 = 15.00.” The customer sees what they used and what they owe. You see what it cost you, what you charged, and the margin.

​
9. API Key

Your credential for talking to MarginFront’s API. Starts with mf_sk_ (secret key — server-side only, full access). The API key identifies your organization — you never need to pass an org ID in your requests. Created in the dashboard under Developer Zone > API Keys. Never put your secret key in frontend code or commit it to git.

​
The metric vs service cost mental model

Signals are what your CUSTOMER sees. Service costs are what YOU see. A customer sees their invoice: Messages: 150 x $0.10 = $15.00 You see your margin dashboard: Messages: 150 events, $2.34 LLM cost, $15.00 revenue, 84% margin Same events, two perspectives. Signals face outward (billing). Service costs face inward (profitability).

​
Setup sequence (the golden path)

Here’s the order things happen, from zero to fully working: 
1. Create Agent
      |
      v
2. Create Signal (tied to the agent)
      |
      v
3. Create Pricing Plan (optional -- skip if you only need cost tracking)
      |
      v
4. Link Plan to Agent (optional -- done automatically when you create the plan)
      |
      v
5. Create Customer
      |
      v
6. Create Subscription (optional -- ties customer + agent + plan together)
      |
      v
7. Send Events (the thing you do every day)
      |
      v
8. See it on the Dashboard (costs, revenue, margins, invoices)
Steps 3, 4, and 6 are optional. If you only care about tracking what your AI costs you (not what you charge your customers), skip them entirely. You can always add pricing plans and subscriptions later — nothing breaks without them.

​
Three integration paths

You can send events to MarginFront three different ways. Pick whichever fits your workflow. 
npm install @marginfront/sdk
Lives in your agent’s code. Sends usage events with automatic batching and retries. If MarginFront is down, events queue locally and retry — your agent never stalls. See the OpenAI recipe for a complete example.

​
REST API (any language)

Same event endpoint (POST /v1/usage/record), raw HTTP. Works from any language or platform — Python, Go, Ruby, curl, whatever. Pass your API key in the x-api-key header. See the Usage Events reference for the full field reference.

​
MCP (for AI coding assistants)

Same API, but your AI coding assistant (like Claude Code or Cursor) calls it for you. Useful for setting up agents, customers, and signals without leaving your editor. See the MCP Setup guide for details.

​
Next steps