> ## Documentation Index
> Fetch the complete documentation index at: https://docs.marginfront.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Setup

> Connect your AI coding assistant to MarginFront in 2 minutes

# 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 **Build > 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:

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

4. Replace `mf_sk_your_key_here` with your real API key.
5. Save the file.
6. 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):

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

4. Replace `mf_sk_your_key_here` with your real API key.
5. Save the file.
6. 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:

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

5. Replace `mf_sk_your_key_here` with your real API key.
6. Save the file.
7. 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.

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

5. Replace `mf_sk_your_key_here` with your real API key.
6. Save the file.
7. 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:

```json theme={null}
"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-service LLM usage event.
* **"Record one cold outreach for customer acme-001 on the outreach-bot. The outreach used Exa search (1 call), Hunter enrichment (1 call), Claude Opus to write the message (4500 input + 1200 output tokens, 1 call), and Pipedream to send (1 call). Track it as ONE event."** -- records a multi-service event where one business outcome (the outreach) was backed by four underlying services. The dashboard shows one event with all four costs rolled up; the Cost-by-service chart splits the total across the search API, the enrichment API, the LLM, and the delivery API.
* **"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
* Generate draft invoices from a subscription's tracked usage
* Email an invoice to the customer with a Stripe Checkout pay-now button (the same Send action the dashboard uses)
* 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)

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

### Tracking from your live product (use the SDK or REST instead)

MCP runs your requests through an AI assistant, so it shines at plain-English, one-at-a-time work: trying things out, looking things up, backfilling old events, and fixing things by hand. It is **not** built to record an event on every request in your live product.

When you're ready to track usage from your running product -- an event each time your agent finishes something you bill for -- put that call in your own code. Use the MarginFront SDK or a direct call to the REST API at `https://api.marginfront.com/v1`. A good way to start: ask MCP to fire one test event so you can watch the connection work, then have your AI assistant write the permanent SDK (or REST) call into your codebase, right at the spot where your agent completes that billable action.

See [Tracking Usage Events](/sdk/tracking-events) for where the SDK code goes, and [SDK vs REST](/api-reference/sdk-vs-rest) if you're deciding between the two.

***

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