@marginfront/mcp

Official Model Context Protocol server for MarginFront. Lets AI agents (Claude, GPT, and any other MCP-compatible client) use MarginFront as a tool. Record usage events, look up customers, check invoices. No integration code required. The agent asks for something in plain English; this server translates into MarginFront API calls.

Full Documentation · Tools Reference · LLM-friendly docs (for agents) · MarginFront Docs

What you get

25 tools that any MCP-compatible AI client can call directly. Organized by purpose:

Connection

• verify: confirm the API key works and see which organization it belongs to

Usage recording

• record_usage / record_usage_batch: log what your customers are using (tokens, quantity, metadata)

Customer lookup

• list_customers / get_customer / create_customer: manage your customer list

Invoices

• list_invoices / get_invoice: read finalized bills and line items

Events

• list_events: browse recorded usage events with filters (pass customerExternalId to scope by your own customer ID)

Analytics (canonical)

• get_usage_analytics: aggregated usage totals plus margin (pass customerExternalId to scope by your own customer ID)
• get_customer_revenue: canonical revenue, cost, margin, and marginPercent for a single customer over a window
• get_cost_metrics: canonical cost totals plus breakdown by agent, customer, signal, day, plan, and model
• get_mrr: canonical MRR (canonical, run-rate, committed, or all three)

Subscriptions

• list_subscriptions / create_subscription: track which customer is on which pricing plan

Pricing setup

• create_pricing_plan / list_pricing_plans / get_pricing_plan: manage pricing plans
• create_pricing_strategy / list_pricing_strategies: add pricing rules (usage, recurring, credit pool, etc.) to plans
• link_plan_to_agent: connect a plan to an agent before subscribing customers

Data repair

• get_needs_attention / map_model: find and resolve events with unrecognized models
• get_missing_volume / fill_volume: find and resolve events with missing token or quantity counts

The signal-naming rule for AI agents

When you use record_usage via this MCP server, the signal_name you pick becomes the line item your user's customer reads on their invoice. Pick it deliberately:

1. Fire ONE call per business outcome. A 50-page report that just finished is ONE record_usage call with quantity: 50, not 50 calls with quantity: 1. Looping multiplies the bill.
2. Match the signal name to how the user wants to bill. Before creating a signal on a user's behalf, ask them what unit goes on the invoice. "Per page" → signal_name: "pages". "Per report" → signal_name: "reports". "Per minute" → signal_name: "minutes".
3. Don't invent internal-sounding names. Bad: llm_call, gpt-4o-call, api-requests. Good: messages, reports-generated, pages, sms-sent, minutes.
4. quantity is the count of that billing unit for this one outcome. A 50-page report fired as pages has quantity: 50. Fired as reports, quantity: 1. Same underlying LLM call, different invoice.

Full mental model (including a three-way comparison of the same LLM call billed three different ways): Choosing your signal name and quantity.

Installation

The MCP server runs as a Node.js process over stdio. You don't npm install it into your app; you configure your MCP client (Claude Desktop, Claude Code, etc.) to spawn it.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or the equivalent on Windows/Linux):

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

Restart Claude Desktop. The MarginFront tools appear automatically.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "${MF_API_SECRET_KEY}",
        "MF_API_BASE_URL": "${MF_API_BASE_URL:-https://api.marginfront.com/v1}"
      }
    }
  }
}

Full setup walkthroughs (including screenshots) are in the MCP setup docs.

Environment variables

Example: AI agent recording usage

Once configured, you can ask your AI assistant things like:

"Record a usage event for customer acme-001 using cs-bot-v2, signal messages, model gpt-4o, 500 input tokens, 100 output tokens."

The assistant calls record_usage under the hood, and MarginFront returns a confirmation with the calculated cost:

Processed 1 event(s): 1 succeeded, 0 failed.

Successful:
  - acme-001 / gpt-4o: $0.00225 (event: 5de8fbf1-...)

If the model isn't in the pricing catalog yet, the event is still saved with cost: null and flagged NEEDS_COST_BACKFILL. The assistant can then call map_model to fix it and backfill every past event with the same model.

Example: asking about revenue and cost

The canonical analytics tools answer business questions in plain English:

"What revenue did we get from customer acme-001 in April?"

Calls get_customer_revenue (after resolving the UUID via list_customers) and returns { revenue, cost, margin, marginPercent } plus a per-strategy-type breakdown.

"What did we spend on model providers this month?"

Calls get_cost_metrics and returns total cost plus breakdowns by agent, customer, signal, day, plan, and model.

"What's our MRR right now?"

Calls get_mrr (defaults to MRR1, last complete calendar month). Ask for "all three" to get MRR1 (actually billed), MRR2 (run-rate trajectory), and MRR3 (contractual floor) in one response.

How it relates to the SDK

• Use @marginfront/mcp when your users / AI agents need MarginFront as a tool callable via natural language.
• Use @marginfront/sdk when you're writing server code in Node and want typed function calls (client.usage.record({ ... })).

They wrap the same REST API; pick whichever fits your integration point.

Troubleshooting

"Missing MF_API_SECRET_KEY environment variable" Your MCP client didn't pass the env var. Check the env block in your MCP config.

"Authentication failed. The API key is invalid or missing" The key was passed but rejected. Verify the key in the Developer Zone and confirm you're using a mf_sk_* secret key (not a mf_pk_* publishable key).

"Could not reach the MarginFront API" Your host is blocking the outbound connection to api.marginfront.com. If you're running a local API for development, set MF_API_BASE_URL=http://localhost:4000/v1.

Source & issues

This package is developed in the Lowcountry-AI/platform monorepo under packages/mcp/.

Report bugs or request features on the issues page.

License

MIT