MCP Tools Reference

All 13 MCP tools with parameters, return values, and example prompts

MarginFront MCP Tools Reference

This is a complete list of every tool the MarginFront MCP server provides. There are 13 tools total, organized into four groups: read-only, write, diagnostic, and destructive.

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.

---

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:

Name	Type	Required	Default	Description
page	number	No	1	Which page of results to show
limit	number	No	20	How many results per page (1-100)
search	string	No	—	Search by customer name or external ID

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:

Name	Type	Required	Description
customerId	string	Yes	The customer’s MarginFront UUID (not their external ID)

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:

Name	Type	Required	Default	Description
status	string	No	—	Filter by status: "draft", "pending", "paid", "overdue", or "void"
customerId	string	No	—	Filter by customer UUID
page	number	No	1	Which page of results
limit	number	No	20	Results per page (1-100)

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:

Name	Type	Required	Description
invoiceId	string	Yes	The invoice’s UUID

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:

Name	Type	Required	Default	Description
page	number	No	1	Which page of results
limit	number	No	20	Results per page (1-100)
customerId	string	No	—	Filter by customer UUID
agentId	string	No	—	Filter by agent UUID
signalId	string	No	—	Filter by signal UUID
startDate	string	No	—	Only show events after this date (ISO 8601 format, e.g. "2026-04-01")
endDate	string	No	—	Only show events before this date (ISO 8601 format)

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

---

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:

Name	Type	Required	Default	Description
startDate	string	Yes	—	Start of the date range (ISO 8601, e.g. "2026-04-01")
endDate	string	Yes	—	End of the date range (ISO 8601, e.g. "2026-04-12")
groupBy	string	No	—	How to break down the data: "agent", "customer", "signal", "model", or "day"

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:

Name	Type	Required	Default	Description
status	string	No	—	Filter by status: "active", "canceled", "past_due", "trialing"
customerId	string	No	—	Filter by customer UUID
page	number	No	1	Which page of results
limit	number	No	20	Results per page (1-100)

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:

Name	Type	Required	Default	Description
customerExternalId	string	Yes	—	Your customer’s ID in your system, e.g. "acme-001"
agentCode	string	Yes	—	The agent/product code from your dashboard, e.g. "cs-bot-v2"
signalName	string	Yes	—	The metric being tracked, e.g. "messages" or "pages_processed"
model	string	Yes	—	The model identifier, e.g. "gpt-4o", "claude-sonnet-4-6", "twilio-sms"
modelProvider	string	Yes	—	The provider name in lowercase, e.g. "openai", "anthropic", "twilio"
inputTokens	number	No	—	Number of input/prompt tokens (for LLM events)
outputTokens	number	No	—	Number of output/completion tokens (for LLM events)
quantity	number	No	1	Number of billing units (for non-LLM events)
usageDate	string	No	now	ISO 8601 date for backdating, e.g. "2026-04-01T00:00:00Z"
metadata	object	No	—	Custom key-value pairs stored with the event (not used for billing)

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:

Name	Type	Required	Description
records	array	Yes	An array of 1-100 usage records. Each record has the same fields as record_usage (see above).

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:

Name	Type	Required	Default	Description
name	string	Yes	—	Customer’s display name, e.g. "Acme Corp"
externalId	string	No	—	Your system’s ID for this customer, e.g. "acme-001"
email	string	No	—	Customer’s email address
phone	string	No	—	Customer’s phone number

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:

Name	Type	Required	Default	Description
startDate	string	No	30 days ago	Only look at events after this date (ISO 8601)
endDate	string	No	now	Only look at events before this date (ISO 8601)

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:

Name	Type	Required	Description
sourceModel	string	Yes	The unknown model name to map FROM, e.g. "gpt-4o-2024-08-06"
sourceProvider	string	Yes	The unknown provider to map FROM, e.g. "openai"
targetPricingId	string	No*	UUID of the target pricing row to map TO
targetModel	string	No*	Known model name to map TO, e.g. "gpt-4o"
targetProvider	string	No*	Known provider to map TO, e.g. "openai"

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