@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 — recording usage events, looking up customers, checking invoices — without writing a single line of integration code. 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

13 tools that any MCP-compatible AI client can call directly:

• verify — confirm the API key works and see which organization it belongs to
• record_usage / record_usage_batch — log what your customers are using (tokens, quantity, metadata)
• list_customers / get_customer / create_customer — manage your customer list
• list_invoices / get_invoice — read finalized bills and line items
• list_events — browse recorded usage events with filters
• get_usage_analytics — aggregated usage totals across customers, agents, signals, or time
• list_subscriptions — see which customer is on which pricing plan
• get_needs_attention — find events where the model isn't in the pricing catalog yet
• map_model — tell MarginFront "this unknown model equals that known one" and backfill missing costs

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.

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