MCP server

Marginal ships a hosted MCP server so the AI agents your team already uses — Claude Code, Cursor, Codex, and any other MCP client — can query your spend data directly: "what did we spend on GPT-5 yesterday?", "which customer cost the most this month?", "did my Marginal integration actually receive events?".

https://api.marginalhq.com/v1/mcp

Access is read-only by construction: the server authenticates read-only API keys (prefix mglr_) and rejects ingest keys, so the key in your agent config can never write events — and a leaked SDK key can never read your spend. Create a read-only key on your project's API keys page by switching the key type to Read-only (MCP).

Connect#

Claude Code:

claude mcp add --transport http marginal https://api.marginalhq.com/v1/mcp \
  --header "Authorization: Bearer mglr_your_key_here"

Cursor, or any client configured with JSON:

{
  "mcpServers": {
    "marginal": {
      "url": "https://api.marginalhq.com/v1/mcp",
      "headers": { "Authorization": "Bearer mglr_your_key_here" }
    }
  }
}

One key = one project. To query several projects, add the server once per project under different names (marginal-prod, marginal-staging, …).

Tools#

Tool	What it answers
`get_project`	Project name, timezone, plan limits, and the registered fields usable as dimensions — agents should call it first.
`get_spend_summary`	The Overview numbers: total, today, yesterday, previous 7 / 30 days.
`get_spend_breakdown`	Spend grouped by model, provider, or any registered field over a range, with filters — the Explorer's group-by.
`get_spend_series`	Spend over time in hour/day/month buckets, optionally split by a dimension.
`list_events`	Raw ingested events — the way an agent verifies an SDK integration end-to-end.
`get_unpriced_models`	Models whose events landed with `cost null` because no price matched.
`get_ingest_requests`	The ingest log (last 7 days) with per-event rejection reasons — integration debugging.
`search_model_prices`	The model price catalog (plus your custom overrides), quoted as USD per 1M tokens.

Everything is scoped to the key's project and respects your plan's data retention and tracked-spend limits, exactly like the dashboard.

Ask your agent#

You don't call tools — you ask questions, and the agent composes the calls. Every agent gets the same orientation from the server (amounts in USD, days in your project's timezone, get_project first for your registered fields), so plain language is enough. Prompts that work well:

Spend checks:

What did we spend yesterday, and which model drove it?

Rank our customers by AI cost this month, with each one's share
of the total.

Spike investigations — the agent chains a time series with filtered breakdowns:

Spend jumped this week. Find which feature and customer caused it,
and tell me whether it's volume (more events) or price (costlier
models).

Cost-aware engineering — from the coding agent you're already working in:

Before we ship: what does the summarize feature cost per event in
production, and what would it cost at 10x volume?

Data hygiene — unpriced models and failing ingest requests, with fixes:

Are any models landing unpriced, and are any ingest requests
failing? Tell me what to fix.

What-if pricing — real token volumes against catalog prices:

We run chat on gpt-4o. Using last week's actual usage, estimate
what the same traffic would cost on gpt-4o-mini.

As a concrete example, the customer-ranking prompt above plays out as: get_project (learn that customer is a registered field) → get_spend_breakdown with group_by: "customer" for the month → an answer like "acme-corp leads at $478.85 (49% of $976.53), then globex at $250.75 (26%) — $54.87 is untagged" — the same numbers, to the cent, that the Explorer shows for that slice.

Verify an integration with your agent#

The MCP server closes the loop on the assistant-driven integration: the same agent that instruments your code can confirm the events landed. After connecting, ask something like:

Send one test completion through our app, then use the marginal MCP
server to confirm the event arrived, was priced, and carries the
customer and feature fields we agreed on.

PreviousDashboard