​

MarginFront MCP Tools Reference

This is a complete list of the core MarginFront MCP tools. There are 32 tools total, organized into groups: read-only, write, diagnostic, destructive, canonical analytics, pricing setup, portal sessions, and catalog discovery. 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 (5)

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 three patterns the same tool accepts:

• Single-service LLM event (chatbots, summarizers, etc.): pass top-level model + modelProvider + inputTokens + outputTokens.
• Single-service non-LLM event (SMS, web scraping, API calls, etc.): pass top-level model + modelProvider + quantity.
• Multi-service event (one outcome backed by multiple underlying services, e.g. one report that called Claude AND queried Google Maps): pass a services[] array, one entry per underlying service. Top-level quantity stays signal-level (default 1). Top-level model / modelProvider are omitted.

The single-service shape and multi-service shape are mutually exclusive. Send top-level model + modelProvider OR send services[], never both, never neither. The MCP tool rejects with a clear English error before the request leaves the agent if you mix shapes. Parameters: What it returns:

• For single-service: the event ID, calculated cost (in USD), and timestamp.
• For multi-service: the parent event ID, rolled-up totalCostUsd (sum across services), a services[] array showing per-service cost + status, and timestamp.

If any service in a multi-service event isn’t in the pricing table, the parent’s totalCostUsd stays null until ALL services are mapped (the cost rule). The services[] response array shows exactly which entries are unresolved so you can call map_model on the right one. Use get_needs_attention to see all unmapped models across all events. Example prompts:

• Single-service: "Record a usage event: customer acme-001 used cs-bot, signal messages, gpt-4o from openai, 500 input tokens, 120 output tokens"
• Multi-service: "Record one cold outreach for customer acme-001 on the outreach-bot. The outreach used Exa search (1 call), Hunter enrichment (1 call), Claude Opus to write the message (4500 input + 1200 output tokens, 1 call), and Pipedream to send (1 call). Track it as ONE event."

Important: If you get a “NEEDS_COST_BACKFILL” response, do NOT re-send the event. The event was saved. The model (or one of the services) 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 — including the choice between single-service shape (top-level model + modelProvider) and multi-service shape (services[]). You can mix all three patterns (single-service LLM, single-service non-LLM, multi-service) in the same batch. Parameters: What it returns: A summary showing how many succeeded, how many failed, and per-record details for each. Successes include the same shape as record_usage. Failed records that were still saved (like NEEDS_COST_BACKFILL or MISSING_VOLUME_DATA) are flagged — do NOT retry those. For multi-service failed records, the response includes a servicesStatus[] array so you see which specific service in the batch entry needs fixing. Example prompt: “Record these for customer acme-001: 3 messages on cs-bot using gpt-4o from openai (200 input / 50 output each), and one cold outreach on outreach-bot that used Exa (1 call), Hunter (1 call), Claude Opus (4500/1200 tokens, 1 call), and Pipedream (1 call).“

---

​

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.

---

​

12. generate_invoice

What it does: Builds a draft invoice from a subscription’s tracked usage. Reads the period’s usage events, applies the subscription’s pricing strategies, and writes a draft invoice with line items and totals — ready to preview, edit, or send. This is the right tool when you want to “bill now” instead of waiting for the end of the billing period. The draft starts in draft status; nothing is sent to the customer until you (or the auto-finalize step) move it to issued. Parameters: What it returns: The full draft invoice, including line items, totals, and the invoice UUID. Example prompt: “Generate a draft invoice for Acme Corp’s Growth Plan subscription using this period’s usage”

---

​

13. send_invoice

What it does: Emails an invoice to the customer with a “Pay Now” button that opens Stripe Checkout pre-filled with the invoice details. Use this after generate_invoice to actually deliver a draft, or to re-send an invoice that has already been issued. The customer’s stored email address is used by default — pass recipientEmail to override (for example, to route the invoice to a different billing contact). Parameters: What it returns: A confirmation including the email provider’s message ID (for delivery tracking) and the address the email was actually sent to (after applying any override). Example prompts:

• “Email the latest draft invoice to Acme Corp”
• “Send invoice inv_abc to [email protected] with the subject ‘May invoice — auto-charge in 5 days’”

Side effect: if the invoice is still a draft when you call this, sending it auto-finalizes the status to issued. This matches the dashboard Send button and the end-of-period auto-finalize step. Once the customer pays via the Stripe Checkout link, the invoice flips to paid automatically — no follow-up call needed.

---

​

Diagnostic Tool (1)

This tool helps you find and fix data issues.

---

​

14. 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).

---

​

15. 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)

​

16. 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?“

---

​

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

​

18. 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?“

---

​

19. 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.”

---

​

20. 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)

​

21. 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”

---

​

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

---

​

23. 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).

---

​

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

---

​

25. list_pricing_strategies

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

---

​

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

---

​

27. 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.”

---

​

Portal Sessions (4)

These four tools let an AI assistant mint and manage one-time portal links — the URLs you send to your customers so they can see their own billing on a MarginFront-hosted page. See the Portal Sessions API reference for the full plain-English explanation.

---

​

28. create_portal_session

What it does: Mints a one-time portal link for a customer. The URL is good for one hour and stops working the moment the customer opens it. Parameters: What it returns: The session ID, the URL to send your customer, the token, customer details, and the expiry timestamp. Example prompt: “Send acme-001 a portal link”

---

​

29. get_portal_session

What it does: Looks up one portal session by ID. Use this to check whether a link has been opened or has expired. Does NOT return the token or url — those are only shown at creation. Parameters: What it returns: Session metadata — customer, expiry, redeem status. Example prompt: “Has Acme opened the portal link I sent yesterday?“

---

​

30. list_portal_sessions

What it does: Lists portal sessions your organization has created. Useful for audit or support. Tokens are intentionally omitted from the response. Parameters: What it returns: A list of session metadata records. Example prompt: “Show me all portal links we sent Acme this month”

---

​

31. revoke_portal_session

What it does: Immediately invalidates a portal session. Use this if you sent a link to the wrong customer or need to cut access early. Hard delete — the session row is removed. Parameters: What it returns: A confirmation that the session was revoked. Example prompt: “Cancel the portal link I sent Acme yesterday”

---

​

Catalog Discovery (1)

This tool lets the AI look up canonical model and provider names from MarginFront’s global service pricing catalog before firing usage events. Use it to avoid the “guess and check until cost resolves” cycle.

---

​

32. list_catalog_services

What it does: Browses the global service catalog — every model and non-LLM service MarginFront can calculate cost for. Filter by provider, service type, or free-text search to find the canonical model + modelProvider names to send with record_usage so cost auto-resolves on ingest. The catalog is read-only and global (not org-scoped). Parameters: What it returns: Paginated catalog entries. Each entry includes canonicalName (what to send as model), provider (what to send as modelProvider), serviceType, per-unit inputCost / outputCost, costUnit, and contextWindow for LLMs. Example prompts:

• “What canonical name should I use for GPT-4o when recording usage?”
• “List every Google service in the MarginFront catalog.”
• “Find the catalog entry for Twilio SMS so I can record an event.”

Tip: Pair this with record_usage — look up the canonical name first, then fire the event using that exact name and provider. Cost resolves automatically without a NEEDS_COST_BACKFILL round trip. See the Services Catalog reference for the full field list.