​

MarginFront MCP Tools Reference

This is a complete list of the core MarginFront MCP tools. There are 25 tools total, organized into groups: read-only, write, diagnostic, destructive, canonical analytics, and pricing setup. Your AI assistant calls these tools automatically when you ask it questions about your MarginFront data. You don’t need to memorize tool names. Just ask in plain English and the AI picks the right tool. Detailed parameters and examples for every tool live in the machine-readable llms-mcp.txt, which is the canonical source the MCP server and AI clients both read.

---

​

Read-Only Tools (8)

These tools look things up without changing anything.

---

​

1. verify

What it does: Checks that your API key is valid and shows which organization it belongs to. This is the “hello world” of MCP — call it first to make sure everything is wired up. Parameters: None. What it returns: Your organization name and a verified status. Example prompt: “Verify my MarginFront connection”

---

​

2. list_customers

What it does: Lists your customers with optional search and pagination. Good for browsing your customer list or finding a specific customer by name. Parameters: What it returns: A list of customers with their names, MarginFront UUIDs, external IDs, and status. Example prompt: “Show me my MarginFront customers”

---

​

3. get_customer

What it does: Gets detailed information about one specific customer, including their subscriptions. Parameters: What it returns: Full customer details — name, email, phone, external ID, status, and all their subscriptions. Example prompt: “Tell me about customer 7a2b3c4d-5e6f-7890-abcd-ef1234567890”

Note: This tool needs the MarginFront UUID, not the external ID you use in your own system. Use list_customers first to find the UUID.

---

​

4. list_invoices

What it does: Lists invoices with optional filters by status or customer. Parameters: What it returns: A list of invoices showing status, amounts, customer name, and dates. Example prompt: “Show me all pending invoices”

---

​

5. get_invoice

What it does: Gets full details about one invoice, including every line item and payment history. Parameters: What it returns: The complete invoice — line items (what was billed), amounts, payment status, customer info, and dates. Example prompt: “Show me the details on invoice 1a2b3c4d-5e6f-7890-abcd-ef1234567890”

---

​

6. list_events

What it does: Lists usage events (the raw records of what your customers actually used) with optional filters. Parameters: What it returns: A list of events, each showing the model used, token counts, calculated cost, customer, and timestamp. Example prompt: “What events were logged today?” or “Show me events for customer acme-001 this week.”

---

​

7. get_usage_analytics

What it does: Gets aggregated usage analytics (totals and trends) for a date range. Unlike list_events which shows individual events, this gives you the big picture — totals, breakdowns, and time-series data. Parameters: What it returns: Summary totals (total cost, total events, total tokens) plus a breakdown grouped however you specified. Example prompt: “Show me usage analytics for April grouped by customer”

---

​

8. list_subscriptions

What it does: Lists customer subscriptions (which customer is on which pricing plan). Parameters: What it returns: A list of subscriptions showing status, plan name, billing dates, and customer info. Example prompt: “Show me all active subscriptions”

---

​

Write Tools (3)

These tools create or modify data. They change things in MarginFront, so the AI will usually confirm before calling them.

---

​

9. record_usage

What it does: Records a single usage event — one measurement of a customer using your AI agent. This is how MarginFront learns what to bill for. There are two kinds of events:

• LLM events (chatbots, summarizers, etc.): pass inputTokens and outputTokens.
• Non-LLM events (SMS, web scraping, API calls, etc.): pass quantity instead.

Parameters: What it returns: The event ID, calculated cost (in USD), and timestamp. If the model isn’t in the pricing table, the event is still saved but cost will be null — use get_needs_attention and map_model to fix it. Example prompt: “Record a usage event: customer acme-001 used cs-bot, signal messages, gpt-4o from openai, 500 input tokens, 120 output tokens”

Important: If you get a “NEEDS_COST_BACKFILL” response, do NOT re-send the event. The event was saved. The model just isn’t in the pricing table yet. Use get_needs_attention to see which models need mapping, then map_model to fix them.

---

​

10. record_usage_batch

What it does: Records multiple usage events at once (1 to 100 per request). Each record has the same fields as record_usage. You can mix LLM events and non-LLM events in the same batch. Parameters: What it returns: A summary showing how many succeeded, how many failed, and per-record details for each. Failed records that were still saved (like NEEDS_COST_BACKFILL) are flagged — do NOT retry those. Example prompt: “Record these usage events: customer acme-001 sent 3 messages on cs-bot using gpt-4o from openai (200 input / 50 output tokens each)“

---

​

11. create_customer

What it does: Creates a new customer in MarginFront. Parameters: What it returns: The newly created customer with their MarginFront UUID. Example prompt: “Create a customer called Beta Corp with external ID beta-001”

Tip: Always set externalId when creating a customer. That’s the ID you’ll use when recording usage events later, so it should match whatever ID you use for this customer in your own system.

---

​

Diagnostic Tool (1)

This tool helps you find and fix data issues.

---

​

12. get_needs_attention

What it does: Finds usage events where the model+provider combination isn’t in the pricing table. These events were saved (the data isn’t lost), but their cost is null because MarginFront doesn’t know how much that model costs. Parameters: What it returns: Groups of unrecognized model+provider combinations, each with a count of how many events are affected. Example prompt: “Are there any MarginFront events with unknown models?”

Important: These events ARE saved — they just have cost=null. Do NOT re-send them. Use map_model (below) to tell MarginFront what pricing to use, and it will backfill the costs automatically.

---

​

Destructive Tool (1)

This tool modifies existing data. “Destructive” sounds scary, but it’s actually a fix-it tool — and it’s safe to run more than once (it’s idempotent, meaning running it twice produces the same result as running it once).

---

​

13. map_model

What it does: Maps an unknown model to a known one in the pricing table, then backfills costs for all affected events. This creates a permanent, organization-scoped mapping — once you map it, future events with the same model+provider will have their costs calculated automatically. You tell it the “source” (the unknown model) and the “target” (the known model to price it as). You can identify the target two ways:

• By name: pass targetModel + targetProvider (e.g., map “gpt-4o-2024-08-06” to “gpt-4o” from “openai”).
• By ID: pass targetPricingId (the UUID of the specific pricing table row).

Parameters:

*You must provide either targetPricingId OR both targetModel + targetProvider. One or the other, not both.

What it returns: Confirmation of the mapping, how many events had their costs backfilled, and the mapping ID. Example prompt: “Map model gpt-4o-2024-08-06 from openai to gpt-4o from openai”

Safe to run again: If you accidentally run this twice with the same inputs, nothing bad happens. It’s idempotent.

---

​

Diagnostic Tools (2)

​

14. get_missing_volume

What it does: Lists usage events that landed in the MISSING_VOLUME_DATA state. events where the agent didn’t send tokens (for LLM calls) or quantity (for non-LLM). The platform stored them anyway, waiting for the volume data to arrive. Parameters: What it returns: A list of incomplete events. Each row includes event ID, customer, agent, signal, and the partial payload, so you can decide what volume to fill in with fill_volume. Example prompt: “Show me any LLM events still missing tokens” or “Which events landed without quantity this month?“

---

​

15. fill_volume

What it does: Supplies the missing volume data for a MISSING_VOLUME_DATA event. Once filled, the platform recalculates usageCost and flips the event to PROCESSED. Parameters: What it returns: The updated event with the calculated usageCost, and its new PROCESSED state. Example prompt: “Fill in 1500 input and 400 output tokens for event abc-123”

Safe to run again: If the event is already PROCESSED, running fill_volume on it returns the existing state without re-computing.

---

​

Canonical Analytics Tools (3)

These tools expose MarginFront’s single source of truth for revenue, cost, and MRR. They return the same numbers the dashboard KPI tiles display.

​

16. get_customer_revenue

What it does: Returns revenue, cost, and margin for a single customer over a date range. Use this when an AI agent needs to answer “how much has this customer paid us?” or “what’s our margin on this account?” without loading the full analytics view. Parameters: What it returns: Revenue (billed invoiced amount over the window), cost (sum of usageCost for attributed events), and margin = revenue − cost. Also breaks down revenue by type (usage, recurring, seat, onetime). Example prompt: “What’s our revenue and margin for Acme Corp this quarter?“

---

​

17. get_cost_metrics

What it does: Returns the full cost breakdown across the organization (or filtered to a single customer / agent). Includes per-day, per-agent, per-customer, per-signal, per-plan, per-model splits. Optional prior-window trend comparison. Parameters: What it returns: Total cost, event counts, and breakdown arrays (byAgent, byCustomer, bySignal, byDay, byPlan, byModel). When includePriorWindow is true, also returns prior with the same shape for the preceding equivalent period. Example prompt: “Break down our AI costs by model for last month” or “Show cost trend for Deal Ops agent week over week.”

---

​

18. get_mrr

What it does: Returns Monthly Recurring Revenue using one of three canonical variants. MarginFront tracks three distinct MRR computations because “what’s our MRR?” has three different right answers depending on what question you’re asking. Parameters: What it returns: The MRR amount for the requested variant + breakdown by revenue type (usage, recurring, seat, onetime). Example prompt: “What was our MRR last month?” (defaults to canonical) or “What’s our run-rate MRR if usage keeps trending?” (runRate) or “What’s our committed MRR floor for forecasting?” (committed).

---

​

Pricing Setup Tools (7)

​

19. create_pricing_plan

What it does: Creates a new pricing plan for an agent. A pricing plan is a container for pricing strategies (which are the per-signal billing rules). Parameters: What it returns: The new plan with its UUID. Example prompt: “Create a Growth plan for our Outreach Writer agent”

---

​

20. list_pricing_plans

What it does: Lists all pricing plans for the organization, with optional filtering by agent. Parameters: What it returns: Array of plans with their UUID, name, description, agent binding, and an embedded list of pricing strategies attached.

---

​

21. get_pricing_plan

What it does: Returns full details on a single pricing plan, including all its pricing strategies and their rates. Parameters: What it returns: Plan with name, description, agent, and every pricing strategy (chargeType, pricingModel, rates, tiers, minimum commitments).

---

​

22. create_pricing_strategy

What it does: Creates a pricing strategy on an existing plan. A strategy is the per-signal rule: “for this metric, charge this way.” Parameters: What it returns: The new strategy’s UUID and validated config.

---

​

23. list_pricing_strategies

What it does: Lists all pricing strategies on a plan. Parameters: What it returns: Array of strategies with their config.

---

​

24. link_plan_to_agent

What it does: Attaches an existing pricing plan to an agent. An agent can be attached to multiple plans (each pricing different customer tiers). Parameters: What it returns: The junction row confirming the link.

---

​

25. create_subscription

What it does: Creates a subscription tying a customer to an agent + plan. Once created, events fired for this (customer, agent, signal) combination bill against this subscription’s pricing strategies. Parameters: What it returns: New subscription with its UUID, scoped to the (customer, agent, plan) triple. Example prompt: “Create a Growth Plan subscription for Acme Corp on the Outreach Writer agent, billed monthly, usage model.”