Quickstart — Integrate MarginFront in 10 Minutes

This guide walks you through the whole integration from nothing to logging a real usage event. We use plain curl so you can follow along regardless of what language your app is written in. The SDK and MCP sections at the end show the same steps using those tools. What you’ll have when you finish:

One customer in MarginFront (representing one of YOUR customers)
One agent (representing your product)
One signal (the metric you track)
One pricing plan and subscription (optional — for revenue tracking)
One real usage event, logged and visible in the dashboard with a calculated cost

The golden path (each step depends on the one before it):

Create agent → Create signal → Create pricing plan → Link plan to agent → Create customer → Create subscription → Send first event → See it on the dashboard

Steps 4-5 are optional if you only need cost tracking without revenue/invoicing. Time required: 10 minutes if you copy-paste, maybe 15 if you want to understand everything as you go.

What you need vs. what you can skip

MarginFront has two levels of setup depending on what you need: Cost tracking (steps 1–6 below) Track what your AI costs you. You need: a customer, an agent, a signal, and an API key. Log events and MarginFront calculates costs automatically. Revenue tracking and invoicing (add steps 4 and 5) Track what you cost AND what you charge your customers. You also need: a pricing plan and a subscription linking a customer to that plan. Without these, MarginFront still tracks costs — it just can’t calculate revenue or generate invoices. You can add pricing plans and subscriptions whenever you’re ready. Nothing breaks if you skip them now. This quickstart walks through everything so you see the full picture, but steps 4 and 5 are clearly marked as optional if you only need cost tracking.

Before you start

You need two things in your terminal:

1. An API key

In the MarginFront dashboard, go to Developer Zone → API Keys. Copy an existing secret key or create a new one. It’ll look like mf_sk_test_.... Export it:

export MF_API_SECRET_KEY="mf_sk_test_..."

That’s all the credentials you need. The API key alone identifies your organization — you don’t need to pass an org ID anywhere.

2. The API base URL

The production API lives at https://api.marginfront.com. All examples below use this URL. If you’re running a local MarginFront API for development, replace https://api.marginfront.com with https://api.marginfront.com in the examples below.

Step 1 — Create a customer

A customer is who you’re billing — one of YOUR end users or companies. In this example we’ll pretend our customer is “Acme Inc.”

curl -X POST https://api.marginfront.com/v1/customers \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Inc",
    "externalId": "acme-001",
    "email": "billing@acme.com"
  }'

What you should see: A JSON response with an id field. Copy it — that’s your customerId. You’ll need it in Step 5. Why this matters: Every usage event is tied to a customer. Without a customer, MarginFront doesn’t know who used what. If something went wrong: see errors.md for what each status code means.

Step 2 — Create an agent

An agent is the product or service that does the actual work. If you have a customer support bot, that’s one agent. A research assistant would be a different agent.

curl -X POST https://api.marginfront.com/v1/agents \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Bot",
    "agentCode": "cs-bot",
    "description": "Our main GPT-4 powered support agent"
  }'

What you should see: A JSON response with an id field. Copy it — that’s your agentId. You’ll need it in Steps 3, 4, and 5. Why this matters: The agentCode (cs-bot) is the handle you’ll use when logging events. It tells MarginFront which product generated the usage.

Step 3 — Create a signal (metric)

A signal is what you measure. For a support bot, the obvious metric is “messages sent.” For a document processor it might be “pages processed.” Replace <paste-agentId-from-step-2> with the UUID from Step 2:

curl -X POST https://api.marginfront.com/v1/signals \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Messages Sent",
    "shortName": "messages",
    "agentId": "<paste-agentId-from-step-2>",
    "type": "usage"
  }'

What you should see: A JSON response with an id field (the signal ID). Why this matters: The shortName (messages) is what you reference in usage events. It tells MarginFront what kind of work happened.

Step 4 — Create a pricing plan (optional — for revenue tracking)

Skip this step if you only need cost tracking. Without a pricing plan, MarginFront still tracks your AI costs. You just won’t see revenue calculations or invoices. Come back and add this when you’re ready to bill your customers.

A pricing plan defines how much you charge per unit of a signal. Think of it as “the Starter Plan for Customer Support Bot.” Replace <paste-agentId-from-step-2>:

curl -X POST https://api.marginfront.com/v1/pricing-plans \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CS Bot Starter Plan",
    "description": "Pay-as-you-go for the support bot",
    "agentId": "<paste-agentId-from-step-2>"
  }'

What you should see: A JSON response with an id. Copy it — that’s your planId. You’ll need it in Step 5.

Note: The actual per-message price is configured through the pricing strategies flow. The dashboard is the easiest place to set up the actual prices after creating the plan container here.

Step 5 — Create a subscription (optional — for revenue tracking)

Skip this step if you only need cost tracking. A subscription ties a customer to a pricing plan. Without it, events are tracked and costs are calculated, but revenue and invoices are not generated.

This is the moment you say “starting now, bill Acme Inc according to the CS Bot Starter Plan.” Replace all three placeholders:

curl -X POST https://api.marginfront.com/v1/subscriptions \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme CS Bot Subscription",
    "customerId": "<paste-customerId-from-step-1>",
    "agentId": "<paste-agentId-from-step-2>",
    "planId": "<paste-planId-from-step-4>",
    "startDate": "2026-04-10T00:00:00.000Z",
    "status": "active",
    "billingCycle": "monthly"
  }'

What you should see: A JSON response with an id (the subscription ID) and status: "active". Acme Inc is now officially subscribed. MarginFront will calculate both cost (what it costs you) and revenue (what you charge Acme) for every event going forward.

Step 6 — Log a usage event (the important one)

This is the endpoint you’ll call all day, every day once you’re live. Every time your support bot sends a message for Acme, you log an event. Notice this endpoint references the customer and agent by their string IDs (customerExternalId and agentCode), not their UUIDs. Five fields are required: customerExternalId, agentCode, signalName, model, and modelProvider.

curl -X POST https://api.marginfront.com/v1/usage/record \
  -H "x-api-key: $MF_API_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {
        "customerExternalId": "acme-001",
        "agentCode": "cs-bot",
        "signalName": "messages",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "inputTokens": 523,
        "outputTokens": 117
      }
    ]
  }'

What you should see:

{
  "processed": 1,
  "successful": 1,
  "failed": 0,
  "results": {
    "success": [
      {
        "customerExternalId": "acme-001",
        "agentCode": "cs-bot",
        "signalName": "messages",
        "model": "gpt-4o",
        "modelProvider": "openai",
        "totalCostUsd": "0.0024780000",
        "eventId": "8a7b6c5d-...",
        "rawEventId": "f1e2d3c4-...",
        "timestamp": "2026-04-12T..."
      }
    ],
    "failed": []
  }
}

That’s it. You just logged a real usage event. MarginFront now knows “Acme Inc used cs-bot to send 1 message, costing 523 input tokens + 117 output tokens on gpt-4o from OpenAI.”

Note: model and modelProvider are both required. modelProvider tells MarginFront which pricing table to check — see usage-events.md for the full field reference and what happens when a model isn’t recognized.

Step 7 — See it worked

Two ways to verify: Option A — Read the usage analytics:

curl "https://api.marginfront.com/v1/analytics/usage?startDate=2026-04-01&endDate=2026-04-30" \
  -H "x-api-key: $MF_API_SECRET_KEY"

You should see a roll-up that includes your event. Option B — Log into the dashboard. Navigate to the Home page. You should see the event and its calculated cost.

You’re done

You just did a full end-to-end integration. Here’s what to do next:

Wire this into your real code. The curl commands above map directly to HTTP calls in any language. The pattern is: set up once (customer, agent, signal), then log usage events from your product code whenever work happens.
Add revenue tracking when you’re ready. If you skipped steps 4 and 5, come back to create a pricing plan and subscription when you want to see what you charge your customers, not just what things cost you.
Batch events if you’re high-volume. The usage record endpoint accepts up to 100 records per call. If you’re logging thousands of events, batching is more efficient than one call per event.
Read usage-events.md. It’s the most important doc. Everything after initial setup is about logging events.

Same thing, using the Node SDK

If your app is a Node.js backend, you can do all of the above with the @marginfront/sdk npm package:

npm install @marginfront/sdk

import { MarginFrontClient } from "@marginfront/sdk";

const mf = new MarginFrontClient(process.env.MF_API_SECRET_KEY);

// Step 1 — Create customer
const customer = await mf.customers.create({
  name: "Acme Inc",
  externalId: "acme-001",
  email: "billing@acme.com",
});

// Steps 2-5 — Agents, signals, plans, and subscriptions are set up
// through the dashboard or curl. The SDK focuses on the high-frequency
// operation: logging events.

// Step 6 — Log usage events (this is the one you'll call most often)
await mf.usage.record({
  customerExternalId: "acme-001",
  agentCode: "cs-bot",
  signalName: "messages",
  model: "gpt-4o",
  modelProvider: "openai",
  inputTokens: 523,
  outputTokens: 117,
});

The SDK wraps the same HTTP calls the curl examples use. By default it runs in fire-and-forget mode — if MarginFront is unreachable, events retry automatically from a local buffer. Your agent never stalls.

Same thing, using MCP

If you use Claude Code, Cursor, or VS Code with an AI assistant, you can do most of this by talking to your AI tool in plain English. Step 1 — Connect MCP. Add this to .mcp.json in your project root:

{
  "mcpServers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "mf_sk_test_..."
      }
    }
  }
}

Step 2 — Verify. Ask your AI: "Verify my MarginFront connection". You should see your organization name. Step 3 — Create a customer. Ask: "Create a MarginFront customer called Acme Inc with external ID acme-001" Step 4 — Log an event. Ask:

"Record a usage event for customer acme-001 on agent cs-bot, signal messages, model gpt-4o from openai, 523 input tokens, 117 output tokens"

Step 5 — Check it worked. Ask: "Show me MarginFront usage analytics for today" Agents, signals, pricing plans, and subscriptions are created in the dashboard — MCP is best for day-to-day operations (recording events, querying data, debugging). See MCP Setup Guide for full details.

Help, something didn’t work

Go back to the step that failed, check the response body for an error message, and cross-reference with errors.md. If you’re still stuck, email team@marginfront.com with:

Which step you’re on
The curl command you ran (with your API key REDACTED — never share it)
The full response body you got back

We’ll get you unstuck.

Getting Started

SDK Guide

MCP Guide

Integration Recipes

Quickstart

Quickstart — Integrate MarginFront in 10 Minutes

What you need vs. what you can skip

Before you start

1. An API key

2. The API base URL

Step 1 — Create a customer

Step 2 — Create an agent

Step 3 — Create a signal (metric)

Step 4 — Create a pricing plan (optional — for revenue tracking)

Step 5 — Create a subscription (optional — for revenue tracking)

Step 6 — Log a usage event (the important one)

Step 7 — See it worked

You’re done

Same thing, using the Node SDK

Same thing, using MCP

Help, something didn’t work

Getting Started

SDK Guide

MCP Guide

Integration Recipes

​Quickstart — Integrate MarginFront in 10 Minutes

​What you need vs. what you can skip

​Before you start

​1. An API key

​2. The API base URL

​Step 1 — Create a customer

​Step 2 — Create an agent

​Step 3 — Create a signal (metric)

​Step 4 — Create a pricing plan (optional — for revenue tracking)

​Step 5 — Create a subscription (optional — for revenue tracking)

​Step 6 — Log a usage event (the important one)

​Step 7 — See it worked

​You’re done

​Same thing, using the Node SDK

​Same thing, using MCP

​Help, something didn’t work

Quickstart — Integrate MarginFront in 10 Minutes

What you need vs. what you can skip

Before you start

1. An API key

2. The API base URL

Step 1 — Create a customer

Step 2 — Create an agent

Step 3 — Create a signal (metric)

Step 4 — Create a pricing plan (optional — for revenue tracking)

Step 5 — Create a subscription (optional — for revenue tracking)

Step 6 — Log a usage event (the important one)

Step 7 — See it worked

You’re done

Same thing, using the Node SDK

Same thing, using MCP

Help, something didn’t work