Package Exports

@marginfront/mcp
@marginfront/mcp/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@marginfront/mcp) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@marginfront/mcp

MCP server for MarginFront — lets AI agents record usage, manage customers, and check invoices through plain English.

What this does

This is a Model Context Protocol server. It connects AI coding tools (Claude Code, Cursor, VS Code Copilot, Claude Desktop) to MarginFront. Once set up, you can say things like "show me my top customers this month" or "list invoices that are overdue" and your AI assistant pulls the data directly.

Setup

You need a MarginFront secret key (starts with mf_sk_). Get one from the MarginFront dashboard under Developer Zone > API Keys.

Claude Code

Create .mcp.json in your project root:

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

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

Add to .cursor/mcp.json in your project root:

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

VS Code / Windsurf / Codex

Add to .vscode/mcp.json:

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

Verify

Open your AI tool and ask: "Verify my MarginFront connection." It should respond with your organization name.

What you can ask

Once connected, try:

"Show me my MarginFront customers"
"What events were logged today?"
"List invoices that are overdue"
"What is my usage analytics for this month?"
"Are there any events that need attention?"
"Record a usage event for customer acme-001 using gpt-4o on agent cs-bot with 500 input tokens and 100 output tokens"
"Create a new customer called Beta Corp with external ID beta-001"

Available tools

Tool	What it does
`verify`	Check that the API key works, see your org info
`record_usage`	Record a single usage event
`record_usage_batch`	Record multiple events at once (up to 100)
`list_customers`	List customers with optional search and pagination
`get_customer`	Get details for one customer
`create_customer`	Create a new customer
`list_invoices`	List invoices with optional status filter
`get_invoice`	Get details for one invoice
`list_events`	List usage events with filters
`get_usage_analytics`	Aggregated analytics for a date range
`list_subscriptions`	List subscriptions with filters
`get_needs_attention`	Events with unknown models that need mapping
`map_model`	Map an unknown model to a known one and backfill costs

What you need set up in MarginFront

For cost tracking (the minimum):

A Customer — who you're tracking usage for
An Agent — your product that does the work
A Signal — the metric you track (belongs to the agent)

Add when you're ready for revenue tracking and invoicing:

A Pricing Plan — how much you charge per unit
A Subscription — ties a customer to a plan

Cost tracking works as soon as you log your first event. Revenue and invoicing require a pricing plan and subscription. You can add those whenever you're ready.

Environment variables

Variable	Required	Default	Description
`MF_API_SECRET_KEY`	Yes	—	Your MarginFront secret key (`mf_sk_...`)
`MF_API_BASE_URL`	No	`https://api.marginfront.com/v1`	API base URL (change for local development)

Questions?

Email team@marginfront.com.