Skip to main content

​
MarginFront MCP Setup Guide

​
What is MCP?

MCP (Model Context Protocol) lets your AI coding assistant talk to MarginFront directly. Instead of writing curl commands or switching to the dashboard, you can say “show me my customers” and your AI tool fetches them. Think of it like giving your AI assistant a phone line to MarginFront — it can look things up, record usage events, and answer billing questions without you leaving your editor.

​
Before You Start

You need three things:
  1. A MarginFront API key that starts with mf_sk_. You can find it (or create one) in the MarginFront dashboard under Developer Zone > API Keys.
  2. Node.js 18 or newer installed on your machine. Check by running node --version in your terminal — the number should be 18 or higher.
  3. One of these AI tools installed: Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, or Codex.

​
Setup by Tool

Pick the tool you use and follow only that section. Each one takes about 60 seconds.

​
Claude Code

  1. Open your project folder in your terminal.
  2. Create a file called .mcp.json in the project root (the top-level folder).
  3. Paste this into the file:
{
  "mcpServers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "mf_sk_your_key_here"
      }
    }
  }
}
  1. Replace mf_sk_your_key_here with your real API key.
  2. Save the file.
  3. Restart Claude Code so it picks up the new config.

​
Claude Desktop

  1. Open Claude Desktop.
  2. Go to Settings > Developer > Edit Config to open claude_desktop_config.json.
  3. Paste this into the file (or merge it with any existing config):
{
  "mcpServers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "mf_sk_your_key_here"
      }
    }
  }
}
  1. Replace mf_sk_your_key_here with your real API key.
  2. Save the file.
  3. Restart Claude Desktop.

​
Cursor

  1. Open your project in Cursor.
  2. Create a folder called .cursor in your project root (if it doesn’t exist already).
  3. Inside .cursor, create a file called mcp.json.
  4. Paste this into the file:
{
  "mcpServers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "mf_sk_your_key_here"
      }
    }
  }
}
  1. Replace mf_sk_your_key_here with your real API key.
  2. Save the file.
  3. Restart Cursor.

​
VS Code / Windsurf / Codex

  1. Open your project in VS Code (or Windsurf or Codex).
  2. Create a folder called .vscode in your project root (if it doesn’t exist already).
  3. Inside .vscode, create a file called mcp.json.
  4. Paste this into the file:
Important: VS Code uses "servers" instead of "mcpServers". This is the only difference from the other tools. 
{
  "servers": {
    "marginfront": {
      "command": "npx",
      "args": ["-y", "@marginfront/mcp"],
      "env": {
        "MF_API_SECRET_KEY": "mf_sk_your_key_here"
      }
    }
  }
}
  1. Replace mf_sk_your_key_here with your real API key.
  2. Save the file.
  3. Restart VS Code.

​
Optional: Custom API URL

By default, the MCP server talks to https://api.marginfront.com/v1. If you’re running MarginFront locally or using a staging server, add MF_API_BASE_URL to the env block: 
"env": {
  "MF_API_SECRET_KEY": "mf_sk_your_key_here",
  "MF_API_BASE_URL": "http://localhost:3001/v1"
}
Most people do not need this.

​
Verify the Connection

Once you’ve set up the config and restarted your tool:
  1. Open a new chat in your AI tool.
  2. Type: “Verify my MarginFront connection”
  3. Your AI tool should respond with your organization name and a “verified” status.
If it works, you’re done with setup. If not, scroll down to Troubleshooting.

​
Example Prompts to Try

Once connected, try any of these to see MCP in action:
  • “Show me my MarginFront customers” — lists all your customers with names and IDs.
  • “What events were logged today?” — shows usage events from today.
  • “How much did customer acme-001 cost this month?” — pulls analytics for a specific customer.
  • “Record a usage event for customer acme-001 on agent cs-bot, signal messages, model gpt-4o from openai, 500 input tokens, 120 output tokens” — records a single LLM usage event.
  • “Are there any events with unknown models?” — checks if any usage events have unrecognized models (meaning cost couldn’t be calculated).
  • “Create a customer called Beta Corp with external ID beta-001” — creates a new customer.

​
What MCP Can and Can’t Do

​
Things you can do through MCP

  • Record usage events (single or batch, up to 100 at a time)
  • Look up customers, invoices, subscriptions, and usage events
  • Pull usage analytics for any date range
  • Create new customers
  • Find events where the model wasn’t recognized (cost = unknown)
  • Map unknown models to known ones so costs get calculated

​
Things you should do in the dashboard instead

  • Create agents (the AI products you’re billing for)
  • Create signals (the metrics you’re tracking, like “messages” or “pages”)
  • Create pricing plans
  • Create subscriptions (assigning a customer to a plan)
  • Generate invoices
The short version: MCP is great for day-to-day work — recording events and querying data. The dashboard is better for initial setup — defining your agents, signals, plans, and subscriptions.

​
Troubleshooting

​
”Tool not found” or MCP tools don’t appear

What happened: Your AI tool can’t find the @marginfront/mcp package. Why: The package isn’t available through npx, or there’s a network issue. Fix:
  1. Open a terminal and run: npx -y @marginfront/mcp --help
  2. If that fails, check your internet connection and make sure npm can reach the registry.
  3. If you’re behind a corporate proxy, you may need to configure npm’s proxy settings.

​
”Authentication failed”

What happened: The API key was rejected. Why: The key is missing, expired, or not a secret key. Fix:
  1. Open your MCP config file and check the MF_API_SECRET_KEY value.
  2. Make sure it starts with mf_sk_ (not mf_pk_ — that’s a publishable key, which doesn’t have permission for most operations).
  3. Make sure there are no extra spaces or quotes around the key.
  4. If you’re not sure the key is valid, go to Developer Zone > API Keys in the dashboard and create a new one.

​
”Connection refused” or “Could not reach the MarginFront API”

What happened: The MCP server can’t connect to the MarginFront API. Why: Either the API is down, or you’re pointing to the wrong URL. Fix:
  1. If you set MF_API_BASE_URL, make sure that server is actually running at that address.
  2. If you’re running locally, make sure the API server is started (cd apps/api-nest && npm run dev).
  3. If you didn’t set MF_API_BASE_URL, the default is https://api.marginfront.com/v1 — check that you can reach it from your network.