Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. πŸ”₯

feat(api): spend an MCP credits balance first on hosted MCP calls (#5455)

Rakshith Ramprakash180db64023c9
diff --git a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts b/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
index ed9b425f5..fd8a7bfbd 100644
--- a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
+++ b/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
@@ -15,6 +15,7 @@ vi.mock("../../lib/logger", () => ({
vi.mock("../../services/autumn/autumn.service", () => ({
autumnService: {
checkCredits: vi.fn(),
+ mcpCreditsAvailable: vi.fn(),
},
CREDITS_FEATURE_ID: "CREDITS",
}));
@@ -49,6 +50,10 @@ import { getTeamBalance } from "../../services/autumn/usage";
const checkCreditsMock = autumnService.checkCredits as MockedFunction<
typeof autumnService.checkCredits
>;
+const mcpCreditsAvailableMock =
+ autumnService.mcpCreditsAvailable as MockedFunction<
+ typeof autumnService.mcpCreditsAvailable
+ >;
const getTeamBalanceMock = getTeamBalance as MockedFunction<
typeof getTeamBalance
>;
@@ -65,6 +70,7 @@ function buildReq(overrides: any = {}): any {
function runMiddleware(
req: any,
+ middleware = checkCreditsMiddleware(),
): Promise<{ res: any; nextErr?: any; nextCalled: boolean }> {
return new Promise(resolve => {
let settled = false;
@@ -90,7 +96,7 @@ function runMiddleware(
nextCalled = true;
settle({ res, nextErr: err });
};
- checkCreditsMiddleware()(req, res, next);
+ middleware(req, res, next);
});
}
@@ -371,3 +377,134 @@ describe("checkCreditsMiddleware – unverified agent-key 50-credit cap", () =>
expect(res.status).not.toHaveBeenCalled();
});
});
+
+describe("checkCreditsMiddleware – MCP credits", () => {
+ const hostedMcpAuth = {
+ team_id: "team_test",
+ org_id: "org_test",
+ hostedMcp: true,
+ };
+
+ const spendsMcpCredits = checkCreditsMiddleware(undefined, undefined, {
+ mcpCredits: true,
+ });
+
+ beforeEach(() => {
+ vi.clearAllMocks();
+ });
+
+ it("runs a hosted MCP call the team's credits can't cover when its MCP credits can", async () => {
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });
+ mcpCreditsAvailableMock.mockResolvedValue(1);
+
+ const req = buildReq({
+ path: "/v2/scrape",
+ body: {},
+ auth: hostedMcpAuth,
+ acuc: { api_key_id: 7 },
+ });
+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).not.toHaveBeenCalled();
+ expect(nextCalled).toBe(true);
+ expect(req.account.remainingCredits).toBe(Infinity);
+ expect(mcpCreditsAvailableMock).toHaveBeenCalledExactlyOnceWith({
+ teamId: "team_test",
+ orgId: "org_test",
+ value: 1,
+ properties: {
+ source: "checkCreditsMiddleware:mcp",
+ path: "/v2/scrape",
+ apiKeyId: 7,
+ },
+ });
+ });
+
+ it("keeps the full crawl limit when MCP credits cover it", async () => {
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 5 });
+ mcpCreditsAvailableMock.mockResolvedValue(100);
+
+ const req = buildReq({ auth: hostedMcpAuth, body: { limit: 100 } });
+ const { res } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).not.toHaveBeenCalled();
+ expect(req.body.limit).toBe(100);
+ expect(mcpCreditsAvailableMock).toHaveBeenCalledWith(
+ expect.objectContaining({ value: 100 }),
+ );
+ });
+
+ it("clamps the crawl limit as today when MCP credits cover only part of it", async () => {
+ checkCreditsMock
+ .mockResolvedValueOnce({ allowed: false, remaining: 5 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 5 });
+ mcpCreditsAvailableMock.mockResolvedValue(40);
+
+ const req = buildReq({ auth: hostedMcpAuth, body: { limit: 100 } });
+ const { res } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).not.toHaveBeenCalled();
+ expect(req.body.limit).toBe(5);
+ });
+
+ // Per-key spend caps limit regular credits only.
+ it("runs a hosted MCP call on MCP credits when its key is over its spend cap", async () => {
+ // A per-key cap denies while the team balance stays healthy.
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 5000 });
+ mcpCreditsAvailableMock.mockResolvedValue(1);
+
+ const req = buildReq({
+ path: "/v2/scrape",
+ body: {},
+ auth: hostedMcpAuth,
+ acuc: { api_key_id: 7 },
+ });
+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).not.toHaveBeenCalled();
+ expect(nextCalled).toBe(true);
+ });
+
+ it("falls back to the existing gate once MCP credits can't cover the call", async () => {
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });
+ mcpCreditsAvailableMock.mockResolvedValue(0);
+
+ const req = buildReq({ auth: hostedMcpAuth });
+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).toHaveBeenCalledWith(402);
+ expect(nextCalled).toBe(false);
+ });
+
+ it("never looks at MCP credits when the team's own credits allow the call", async () => {
+ checkCreditsMock.mockResolvedValue({ allowed: true, remaining: 100 });
+
+ const req = buildReq({ auth: hostedMcpAuth });
+ const { res } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).not.toHaveBeenCalled();
+ expect(mcpCreditsAvailableMock).not.toHaveBeenCalled();
+ });
+
+ it("never looks at MCP credits for a call the hosted MCP did not make", async () => {
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });
+
+ const req = buildReq({ body: { limit: 100, origin: "mcp-fastmcp" } });
+ const { res } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).toHaveBeenCalledWith(402);
+ expect(mcpCreditsAvailableMock).not.toHaveBeenCalled();
+ });
+
+ it("never looks at MCP credits on a route whose billing doesn't spend them", async () => {
+ checkCreditsMock.mockResolvedValue({ allowed: false, remaining: 0 });
+ mcpCreditsAvailableMock.mockResolvedValue(100);
+
+ const req = buildReq({ path: "/v2/extract", auth: hostedMcpAuth });
+ const { res, nextCalled } = await runMiddleware(req);
+
+ expect(res.status).toHaveBeenCalledWith(402);
+ expect(nextCalled).toBe(false);
+ expect(mcpCreditsAvailableMock).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts b/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts
index 141c644b4..6a0ec8dcb 100644
--- a/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts
+++ b/apps/api/src/__tests__/routes/research-credit-gate.routes.test.ts
@@ -34,18 +34,24 @@ vi.mock("../../services/billing/credit_billing", () => ({
}));
vi.mock("../../services/autumn/autumn.service", () => ({
- autumnService: { checkCredits: vi.fn() },
+ autumnService: { checkCredits: vi.fn(), mcpCreditsAvailable: vi.fn() },
CREDITS_FEATURE_ID: "CREDITS",
SEARCH_CREDITS_FEATURE_ID: "SEARCH_CREDITS",
}));
const checkCredits = vi.mocked(autumnService.checkCredits);
+const mcpCreditsAvailable = vi.mocked(autumnService.mcpCreditsAvailable);
-function appWith(orgId: string | undefined) {
+function appWith(orgId: string | undefined, hostedMcp = false) {
const app = express();
app.use(express.json());
app.use((req: any, _res, next) => {
- req.auth = { team_id: "team-test", org_id: orgId, plan: "standard" };
+ req.auth = {
+ team_id: "team-test",
+ org_id: orgId,
+ plan: "standard",
+ ...(hostedMcp ? { hostedMcp: true } : {}),
+ };
req.acuc = { api_key_id: 4 };
next();
});
@@ -109,6 +115,19 @@ describe.each([
expect(res.statusCode).toBe(200);
expect(checkCredits).not.toHaveBeenCalled();
});
+
+ it("serves a hosted MCP search the team's MCP credits can cover", async () => {
+ checkCredits.mockResolvedValue({ allowed: false, remaining: 0 });
+ mcpCreditsAvailable.mockResolvedValue(2);
+
+ const res = await request(appWith("org-test", true)).get(path);
+
+ expect(res.statusCode).toBe(200);
+ expect(upstreamCalls).toHaveLength(1);
+ expect(mcpCreditsAvailable).toHaveBeenCalledWith(
+ expect.objectContaining({ teamId: "team-test", value: 2 }),
+ );
+ });
});
it("leaves free paper search ungated", async () => {
diff --git a/apps/api/src/config.ts b/apps/api/src/config.ts
index e42e46c14..2837f0c07 100644
--- a/apps/api/src/config.ts
+++ b/apps/api/src/config.ts
@@ -305,6 +305,11 @@ const configSchema = z.object({
MCP_ACTION_LOG_SECRET: z.string().optional(),
MCP_ACTION_LOG_STORAGE_ENABLED: z.stringbool().default(false),
MCP_ACTION_LOG_WRITES_ENABLED: z.stringbool().default(false),
+ // Autumn feature id of the balance hosted MCP calls spend first (see
+ // AutumnService.trackHostedMcpCredits).
+ MCP_CREDITS_FEATURE_ID: emptyStringAsDefault(
+ z.string().trim().min(1).default("MCP_CREDITS"),
+ ),
// Agent auth discovery (RFC 9728 WWW-Authenticate on 401)
AGENT_AUTH_RESOURCE_METADATA_URL: z
diff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.ts
index 4f51d1d5b..44c7b65df 100644
--- a/apps/api/src/controllers/__tests__/auth.test.ts
+++ b/apps/api/src/controllers/__tests__/auth.test.ts
@@ -1245,6 +1245,71 @@ describe("authenticateUser", () => {
expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");
});
+ it("marks the verified hosted MCP calls on the auth result, and no others", async () => {
+ const delegated = await authenticateUser(
+ requestWith("Bearer " + signDelegation()),
+ {},
+ RateLimiterMode.Scrape,
+ );
+ const relayed = await authenticateUser(
+ requestWith(API_KEY, {
+ headers: { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },
+ }),
+ {},
+ RateLimiterMode.Crawl,
+ );
+ const selfDeclared = await authenticateUser(
+ requestWith(API_KEY, {
+ body: { origin: "mcp-fastmcp" },
+ headers: {
+ "x-origin": "mcp-fastmcp",
+ "x-firecrawl-keyless-secret": "not-the-secret",
+ },
+ }),
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(delegated).toMatchObject({ success: true, hostedMcp: true });
+ expect(relayed).toMatchObject({ success: true, hostedMcp: true });
+ expect(selfDeclared.success).toBe(true);
+ expect(selfDeclared).not.toHaveProperty("hostedMcp");
+ });
+
+ it("never marks an OAuth access token as a hosted MCP call, even with the proxy secret", async () => {
+ config.OAUTH_INTROSPECT_URL = "https://example.test/introspect";
+ config.OAUTH_INTROSPECT_SECRET = "secret";
+ vi.stubGlobal(
+ "fetch",
+ vi.fn().mockResolvedValue(
+ new Response(
+ JSON.stringify({
+ active: true,
+ api_key: "fc-00000000000000004000800000000000",
+ scope: "firecrawl:global",
+ client_id: "client-1",
+ team_id: "team-1",
+ exp: Math.floor(Date.now() / 1000) + 60,
+ aud: "https://api.firecrawl.dev/",
+ credential_purpose: "hosted_mcp_oauth",
+ }),
+ { status: 200, headers: { "Content-Type": "application/json" } },
+ ),
+ ),
+ );
+
+ const auth = await authenticateUser(
+ requestWith("Bearer fco_rest_grant_token", {
+ headers: { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },
+ }),
+ {},
+ RateLimiterMode.Crawl,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(auth).not.toHaveProperty("hostedMcp");
+ });
+
it.each([
["", {}],
[
diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.ts
index ae0171aaa..a615fc005 100644
--- a/apps/api/src/controllers/auth.ts
+++ b/apps/api/src/controllers/auth.ts
@@ -1139,6 +1139,7 @@ async function supaAuthenticateUser(
}
}
+ let hostedMcpCall = false;
if (chunk !== null) {
// Calls the hosted MCP makes on routes that opt in (every v2 route) get a
// raised per-minute minimum, and scrape calls a raised concurrency
@@ -1148,14 +1149,15 @@ async function supaAuthenticateUser(
// `fco_` tokens never qualify: the hosted MCP keeps those for the issuer,
// so a REST call carrying one comes from the client itself. Origin and
// integration are client-set, so they never change the limit.
+ hostedMcpCall =
+ hostedMcpDelegation ||
+ (!token.startsWith("fco_") &&
+ timingSafeSecretEqual(
+ req.headers["x-firecrawl-keyless-secret"],
+ config.KEYLESS_PROXY_SECRET,
+ ));
const hostedMcpRaise =
- options?.hostedMcpRateLimit === true &&
- (hostedMcpDelegation ||
- (!token.startsWith("fco_") &&
- timingSafeSecretEqual(
- req.headers["x-firecrawl-keyless-secret"],
- config.KEYLESS_PROXY_SECRET,
- )));
+ options?.hostedMcpRateLimit === true && hostedMcpCall;
// The tiers follow the team's own plan multiplier, not the one trusted
// agent traffic floors at hobby, so a free team never gets the hobby tier.
const hostedMcpLimiter = hostedMcpRaise
@@ -1264,5 +1266,6 @@ async function supaAuthenticateUser(
team_id: teamId ?? undefined,
org_id: chunk?.org_id ?? null,
chunk,
+ ...(hostedMcpCall ? { hostedMcp: true } : {}),
};
}
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.ts
index db0e066a6..f7fc262bc 100644
--- a/apps/api/src/controllers/v1/types.ts
+++ b/apps/api/src/controllers/v1/types.ts
@@ -1318,6 +1318,9 @@ type AuthObject = {
// Set only by authMiddleware from the raw request; controllers may re-parse
// the body and drop `__agentInterop`, so read this instead.
agentInterop?: AgentInteropStatus;
+ // Set only by authMiddleware, from the hosted MCP verification in
+ // supaAuthenticateUser; never from the request body or headers directly.
+ hostedMcp?: boolean;
};
type Account = {
diff --git a/apps/api/src/controllers/v2/batch-scrape.ts b/apps/api/src/controllers/v2/batch-scrape.ts
index ea304cad1..285ac3fea 100644
--- a/apps/api/src/controllers/v2/batch-scrape.ts
+++ b/apps/api/src/controllers/v2/batch-scrape.ts
@@ -150,6 +150,7 @@ export async function batchScrapeController(
? { endpoint: "agent" as const, jobId: id }
: { endpoint: "batch_scrape" as const, jobId: id }),
externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
};
const logger = _logger.child({
crawlId: id,
diff --git a/apps/api/src/controllers/v2/crawl.ts b/apps/api/src/controllers/v2/crawl.ts
index 1438ae7c6..6cd2d9e5e 100644
--- a/apps/api/src/controllers/v2/crawl.ts
+++ b/apps/api/src/controllers/v2/crawl.ts
@@ -134,7 +134,11 @@ export async function crawlController(
// No chargeId: a fresh crawl id is minted per request and the
// rejected crawl is never persisted or queued, so there is no
// stable per-charge identity that could dedupe a retry.
- { endpoint: "crawl" },
+ {
+ endpoint: "crawl",
+ externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
+ },
).catch(error => {
_logger.error(
`Failed to bill team ${req.auth.team_id} for ${threatScanCredits} threat scan credit(s): ${error}`,
@@ -402,6 +406,7 @@ export async function crawlController(
endpoint: "crawl",
jobId: id,
externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
},
crawl_id: id,
webhook: req.body.webhook,
diff --git a/apps/api/src/controllers/v2/map.ts b/apps/api/src/controllers/v2/map.ts
index 363ed14e2..5eb32af53 100644
--- a/apps/api/src/controllers/v2/map.ts
+++ b/apps/api/src/controllers/v2/map.ts
@@ -149,6 +149,7 @@ export async function mapController(
// map charge below, even if both ever billed the same mapId.
chargeId: `${mapId}:avgrab`,
externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
},
).catch(error => {
logger.error(
@@ -292,6 +293,7 @@ export async function mapController(
externalRequestId: externalRequestId(req),
jobId: mapId,
chargeId: mapId,
+ hostedMcp: req.auth.hostedMcp,
},
).catch(error => {
logger.error("Failed to bill team for map credits", {
diff --git a/apps/api/src/controllers/v2/parse.ts b/apps/api/src/controllers/v2/parse.ts
index bfecd83c1..6ea287874 100644
--- a/apps/api/src/controllers/v2/parse.ts
+++ b/apps/api/src/controllers/v2/parse.ts
@@ -375,6 +375,7 @@ export async function parseController(
? { endpoint: "agent" as const, jobId }
: { endpoint: "parse" as const, jobId }),
externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
};
if (
diff --git a/apps/api/src/controllers/v2/research-proxy.ts b/apps/api/src/controllers/v2/research-proxy.ts
index e5d4863d4..c1552f307 100644
--- a/apps/api/src/controllers/v2/research-proxy.ts
+++ b/apps/api/src/controllers/v2/research-proxy.ts
@@ -37,6 +37,7 @@ const searchCreditGate = () =>
checkCreditsMiddleware(
SEARCH_CREDITS_PER_TEN_RESULTS,
SEARCH_CREDITS_FEATURE_ID,
+ { mcpCredits: true },
);
const ZDR_SEARCH_CREDITS_PER_TEN_RESULTS = 10;
@@ -468,6 +469,7 @@ function createResearchController(
endpoint: endpoint.billAs === "scrape" ? "scrape" : "search",
jobId,
chargeId: jobId,
+ hostedMcp: authedReq.auth.hostedMcp,
},
).catch(billingError => {
logger.error("Failed to bill research request", {
diff --git a/apps/api/src/controllers/v2/scrape.ts b/apps/api/src/controllers/v2/scrape.ts
index f81fddc73..1f89cd99a 100644
--- a/apps/api/src/controllers/v2/scrape.ts
+++ b/apps/api/src/controllers/v2/scrape.ts
@@ -225,6 +225,7 @@ export async function scrapeController(
? { endpoint: "agent" as const, jobId }
: { endpoint: "scrape" as const, jobId }),
externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
};
if (
diff --git a/apps/api/src/controllers/v2/search.ts b/apps/api/src/controllers/v2/search.ts
index e43b4782b..6f43f2d41 100644
--- a/apps/api/src/controllers/v2/search.ts
+++ b/apps/api/src/controllers/v2/search.ts
@@ -315,6 +315,7 @@ async function searchControllerInner(
? { endpoint: "agent" as const, jobId }
: { endpoint: "search" as const, jobId }),
externalRequestId: externalRequestId(req),
+ hostedMcp: req.auth.hostedMcp,
};
logger = logger.child({
diff --git a/apps/api/src/controllers/v2/types.ts b/apps/api/src/controllers/v2/types.ts
index dc8d05c39..ab9df62cc 100644
--- a/apps/api/src/controllers/v2/types.ts
+++ b/apps/api/src/controllers/v2/types.ts
@@ -2120,6 +2120,9 @@ type AuthObject = {
// Set only by authMiddleware from the raw request; controllers may re-parse
// the body and drop `__agentInterop`, so read this instead.
agentInterop?: AgentInteropStatus;
+ // Set only by authMiddleware, from the hosted MCP verification in
+ // supaAuthenticateUser; never from the request body or headers directly.
+ hostedMcp?: boolean;
};
type Account = {
diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.ts
index 743053bcd..f904326a9 100644
--- a/apps/api/src/routes/shared.ts
+++ b/apps/api/src/routes/shared.ts
@@ -48,6 +48,8 @@ import { resolveIntegration } from "../utils/integration";
export function checkCreditsMiddleware(
_minimum?: number,
featureId: string = CREDITS_FEATURE_ID,
+ // Set on routes whose billing spends a hosted MCP call's MCP credits first.
+ { mcpCredits = false }: { mcpCredits?: boolean } = {},
): (req: RequestWithAuth, res: Response, next: NextFunction) => void {
return (req, res, next) => {
let minimum = _minimum;
@@ -191,6 +193,27 @@ export function checkCreditsMiddleware(
return next();
}
+ // A hosted MCP call the team's balance can't cover still runs when its
+ // MCP credits can, which billing then spends first (see billTeam).
+ if (
+ !autumnResult.allowed &&
+ mcpCredits &&
+ req.auth.hostedMcp &&
+ (await autumnService.mcpCreditsAvailable({
+ teamId: req.auth.team_id,
+ orgId,
+ value: requestedCredits,
+ properties: {
+ source: "checkCreditsMiddleware:mcp",
+ path: req.path,
+ apiKeyId: req.acuc?.api_key_id ?? null,
+ },
+ })) >= requestedCredits
+ ) {
+ req.account = { remainingCredits: Infinity };
+ return next();
+ }
+
const success = autumnResult.allowed;
// When Autumn allows the request (including overage), don't let a
// small remaining balance clamp downstream limits (e.g. crawl).
@@ -322,9 +345,14 @@ export function authMiddleware(
}
}
- const { team_id, org_id, chunk } = auth;
+ const { team_id, org_id, chunk, hostedMcp } = auth;
- req.auth = { team_id, org_id, agentInterop: agentInteropStatus(req) };
+ req.auth = {
+ team_id,
+ org_id,
+ agentInterop: agentInteropStatus(req),
+ ...(hostedMcp ? { hostedMcp: true } : {}),
+ };
req.acuc = chunk ?? undefined;
next();
})().catch(err => next(err));
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 5b0e2fca6..4865edb9e 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -213,7 +213,9 @@ v2Router.post(
}),
inferIntegrationMiddleware,
restrictedOptionsCountryCheck,
- checkCreditsMiddleware(undefined, SEARCH_CREDITS_FEATURE_ID),
+ checkCreditsMiddleware(undefined, SEARCH_CREDITS_FEATURE_ID, {
+ mcpCredits: true,
+ }),
blocklistMiddleware,
wrap(searchController),
);
@@ -257,7 +259,7 @@ v2Router.post(
"/parse",
authMiddleware(RateLimiterMode.Scrape, { allowKeyless: true }),
restrictedOptionsCountryCheck,
- checkCreditsMiddleware(1),
+ checkCreditsMiddleware(1, undefined, { mcpCredits: true }),
parsePayloadMiddleware,
inferIntegrationMiddleware,
wrap(parseController),
@@ -271,7 +273,7 @@ v2Router.post(
}),
inferIntegrationMiddleware,
restrictedOptionsCountryCheck,
- checkCreditsMiddleware(1),
+ checkCreditsMiddleware(1, undefined, { mcpCredits: true }),
scrapeBlocklistMiddleware,
wrap(scrapeController),
);
@@ -304,7 +306,7 @@ v2Router.post(
authMiddleware(RateLimiterMode.Scrape, { allowAgentManagedKey: true }),
inferIntegrationMiddleware,
restrictedOptionsCountryCheck,
- checkCreditsMiddleware(),
+ checkCreditsMiddleware(undefined, undefined, { mcpCredits: true }),
blocklistMiddleware,
wrap(batchScrapeController),
);
@@ -313,7 +315,7 @@ v2Router.post(
"/map",
authMiddleware(RateLimiterMode.Map),
inferIntegrationMiddleware,
- checkCreditsMiddleware(1),
+ checkCreditsMiddleware(1, undefined, { mcpCredits: true }),
blocklistMiddleware,
wrap(mapController),
);
@@ -323,7 +325,7 @@ v2Router.post(
authMiddleware(RateLimiterMode.Crawl),
inferIntegrationMiddleware,
restrictedOptionsCountryCheck,
- checkCreditsMiddleware(),
+ checkCreditsMiddleware(undefined, undefined, { mcpCredits: true }),
scrapeBlocklistMiddleware,
idempotencyMiddleware,
wrap(crawlController),
diff --git a/apps/api/src/services/autumn/__tests__/mcp-credits.test.ts b/apps/api/src/services/autumn/__tests__/mcp-credits.test.ts
new file mode 100644
index 000000000..14b61b177
--- /dev/null
+++ b/apps/api/src/services/autumn/__tests__/mcp-credits.test.ts
@@ -0,0 +1,369 @@
+/**
+ * Unit tests for hosted MCP charges in AutumnService: how much the team's MCP
+ * credits can pay (mcpCreditsAvailable), and how a charge is split between
+ * them and the endpoint's own feature (trackHostedMcpCredits).
+ */
+
+import { vi } from "vitest";
+
+const { mockCheck, mockTrack, mockAutumnClient, state, redis } = vi.hoisted(
+ () => {
+ const store = new Map<string, string>();
+ const redis = {
+ store,
+ get: vi.fn(async (key: string) => store.get(key) ?? null),
+ set: vi.fn(async (key: string, value: unknown, ...args: unknown[]) => {
+ if (args.includes("NX") && store.has(key)) return null;
+ store.set(key, String(value));
+ return "OK";
+ }),
+ };
+ const mockCheck = vi.fn<(args: any) => Promise<any>>();
+ const mockTrack = vi.fn<(args: any) => Promise<void>>();
+ const mockAutumnClient = {
+ customers: { getOrCreate: vi.fn(), get: vi.fn() },
+ entities: {
+ get: vi.fn().mockResolvedValue({ id: "team-1" }),
+ create: vi.fn(),
+ },
+ balances: { finalize: vi.fn() },
+ check: mockCheck,
+ track: mockTrack,
+ };
+ return {
+ mockCheck,
+ mockTrack,
+ mockAutumnClient,
+ state: { gatewayStubRow: null as unknown },
+ redis,
+ };
+ },
+);
+
+vi.mock("../client", () => ({
+ autumnClient: mockAutumnClient,
+}));
+
+vi.mock("../../queue-service", () => ({
+ getFirebillTrackRetryQueue: () => ({ add: vi.fn() }),
+ getRedisConnection: () => redis,
+}));
+
+vi.mock("../../../db/connection", () => ({
+ get dbRr() {
+ return {
+ select: () => ({
+ from: () => ({
+ where: () => ({
+ limit: () =>
+ Promise.resolve(
+ state.gatewayStubRow ? [state.gatewayStubRow] : [],
+ ),
+ }),
+ }),
+ }),
+ };
+ },
+}));
+
+vi.mock("../../../config", () => ({
+ config: { MCP_CREDITS_FEATURE_ID: "MCP_CREDITS_FROM_CONFIG" },
+}));
+
+import { AutumnService, MCP_CREDITS_FEATURE_ID } from "../autumn.service";
+
+const charge = {
+ teamId: "team-1",
+ orgId: "org-1",
+ value: 5,
+ properties: { source: "billTeam", endpoint: "scrape" },
+ featureId: "CREDITS",
+ idempotencyKey: "fc:track:scrape:job-1",
+ externalRequestId: "op-1",
+};
+
+/** MCP credits balance as Autumn's check reports it. */
+function mcpBalance(remaining: number | null) {
+ mockCheck.mockImplementation(async ({ featureId, requiredBalance }) => ({
+ allowed:
+ featureId === MCP_CREDITS_FEATURE_ID &&
+ remaining !== null &&
+ remaining >= requiredBalance,
+ customerId: "org-1",
+ balance: remaining === null ? null : { remaining },
+ }));
+}
+
+/** The Autumn track calls a run of fn makes. */
+async function tracksOf(fn: (service: AutumnService) => Promise<unknown>) {
+ mockTrack.mockClear();
+ await fn(new AutumnService());
+ return mockTrack.mock.calls.map(([args]) => args);
+}
+
+beforeEach(() => {
+ vi.clearAllMocks();
+ state.gatewayStubRow = null;
+ redis.store.clear();
+ mockTrack.mockResolvedValue(undefined);
+ mcpBalance(100);
+});
+
+describe("mcpCreditsAvailable", () => {
+ it("reads the feature id from config", () => {
+ expect(MCP_CREDITS_FEATURE_ID).toBe("MCP_CREDITS_FROM_CONFIG");
+ });
+
+ it("pays the whole charge when the MCP credits cover it", async () => {
+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(5);
+ expect(mockCheck).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({
+ customerId: "org-1",
+ entityId: "team-1",
+ featureId: MCP_CREDITS_FEATURE_ID,
+ requiredBalance: 5,
+ }),
+ );
+ });
+
+ it("pays what is left when the MCP credits fall short", async () => {
+ mcpBalance(3.5);
+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(3);
+ });
+
+ it.each([
+ ["used up", 0],
+ ["missing from the team's plan", null],
+ ])("pays nothing when the MCP credits are %s", async (_name, remaining) => {
+ mcpBalance(remaining);
+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(0);
+ });
+
+ it("pays nothing when Autumn can't answer", async () => {
+ mockCheck.mockRejectedValue(new Error("ECONNRESET"));
+ expect(await new AutumnService().mcpCreditsAvailable(charge)).toBe(0);
+ });
+
+ it("never asks Autumn for a partner-provisioned or preview team, or a zero charge", async () => {
+ const service = new AutumnService();
+ state.gatewayStubRow = { team_id: "team-1" };
+ expect(await service.mcpCreditsAvailable(charge)).toBe(0);
+ state.gatewayStubRow = null;
+ expect(
+ await service.mcpCreditsAvailable({ ...charge, teamId: "preview_1" }),
+ ).toBe(0);
+ expect(await service.mcpCreditsAvailable({ ...charge, value: 0 })).toBe(0);
+ expect(mockCheck).not.toHaveBeenCalled();
+ });
+});
+
+describe("trackHostedMcpCredits", () => {
+ it("tracks the whole charge on MCP credits that cover it", async () => {
+ const tracks = await tracksOf(service =>
+ service
+ .trackHostedMcpCredits(charge)
+ .then(result =>
+ expect(result).toEqual({ tracked: true, mcpCredits: 5 }),
+ ),
+ );
+
+ expect(tracks).toEqual([
+ expect.objectContaining({
+ featureId: MCP_CREDITS_FEATURE_ID,
+ value: 5,
+ properties: charge.properties,
+ }),
+ ]);
+ });
+
+ it("splits a charge the MCP credits only partly cover", async () => {
+ mcpBalance(3);
+
+ const tracks = await tracksOf(service =>
+ service
+ .trackHostedMcpCredits(charge)
+ .then(result =>
+ expect(result).toEqual({ tracked: true, mcpCredits: 3 }),
+ ),
+ );
+
+ expect(tracks).toHaveLength(2);
+ expect(tracks).toContainEqual(
+ expect.objectContaining({ featureId: MCP_CREDITS_FEATURE_ID, value: 3 }),
+ );
+ expect(tracks).toContainEqual(
+ expect.objectContaining({
+ featureId: "CREDITS",
+ value: 2,
+ overageBehavior: "overflow",
+ }),
+ );
+ });
+
+ it("gives the MCP part its own firebill idempotency key", async () => {
+ mcpBalance(3);
+ const service = new AutumnService();
+ const trackCredits = vi.spyOn(service, "trackCredits");
+
+ await service.trackHostedMcpCredits(charge);
+
+ expect(trackCredits).toHaveBeenCalledWith(
+ expect.objectContaining({
+ featureId: MCP_CREDITS_FEATURE_ID,
+ idempotencyKey: "fc:track:scrape:job-1:mcp",
+ }),
+ );
+ expect(trackCredits).toHaveBeenCalledWith({ ...charge, value: 2 });
+ });
+
+ it.each([
+ ["used up", 0],
+ ["missing from the team's plan", null],
+ ])(
+ "tracks exactly what trackCredits would when the MCP credits are %s",
+ async (_name, remaining) => {
+ mcpBalance(remaining);
+
+ const hostedMcp = await tracksOf(service =>
+ service
+ .trackHostedMcpCredits(charge)
+ .then(result =>
+ expect(result).toEqual({ tracked: true, mcpCredits: 0 }),
+ ),
+ );
+ const regular = await tracksOf(service => service.trackCredits(charge));
+
+ expect(hostedMcp).toEqual(regular);
+ expect(hostedMcp).toEqual([
+ expect.objectContaining({ featureId: "CREDITS", value: 5 }),
+ ]);
+ },
+ );
+
+ it("reports an untracked MCP part as not paid by MCP credits", async () => {
+ mcpBalance(3);
+ mockTrack.mockImplementation(async ({ featureId }) => {
+ if (featureId === MCP_CREDITS_FEATURE_ID) throw new Error("track failed");
+ });
+
+ expect(await new AutumnService().trackHostedMcpCredits(charge)).toEqual({
+ tracked: false,
+ mcpCredits: 0,
+ });
+ });
+});
+
+describe("refundHostedMcpCredits", () => {
+ const refund = { ...charge, idempotencyKey: "fc:refund:scrape:job-1" };
+
+ it("refunds each part of a split charge to the balance it was tracked on", async () => {
+ const service = new AutumnService();
+ const refundCredits = vi.spyOn(service, "refundCredits");
+
+ expect(
+ await service.refundHostedMcpCredits({ ...refund, mcpCredits: 3 }),
+ ).toBe(true);
+
+ expect(refundCredits).toHaveBeenCalledTimes(2);
+ expect(refundCredits).toHaveBeenCalledWith({
+ ...refund,
+ value: 3,
+ featureId: MCP_CREDITS_FEATURE_ID,
+ idempotencyKey: "fc:refund:scrape:job-1:mcp",
+ });
+ expect(refundCredits).toHaveBeenCalledWith({ ...refund, value: 2 });
+ });
+
+ it("refunds a charge MCP credits paid in full to them only", async () => {
+ const service = new AutumnService();
+ const refundCredits = vi.spyOn(service, "refundCredits");
+
+ await service.refundHostedMcpCredits({ ...refund, mcpCredits: 5 });
+
+ expect(refundCredits).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ value: 5, featureId: MCP_CREDITS_FEATURE_ID }),
+ );
+ });
+
+ it("refunds exactly as refundCredits would when MCP credits paid nothing", async () => {
+ const service = new AutumnService();
+ const refundCredits = vi.spyOn(service, "refundCredits");
+
+ await service.refundHostedMcpCredits({ ...refund, mcpCredits: 0 });
+
+ expect(refundCredits).toHaveBeenCalledExactlyOnceWith(refund);
+ });
+});
+
+describe("hosted MCP charge retries", () => {
+ it("splits a retried charge as the first attempt did, after it used the MCP credits up", async () => {
+ mcpBalance(5);
+ const first = await tracksOf(service =>
+ service.trackHostedMcpCredits(charge),
+ );
+ mcpBalance(0);
+ const retry = await tracksOf(service =>
+ service
+ .trackHostedMcpCredits(charge)
+ .then(result =>
+ expect(result).toEqual({ tracked: true, mcpCredits: 5 }),
+ ),
+ );
+
+ expect(retry).toEqual(first);
+ expect(retry).toEqual([
+ expect.objectContaining({ featureId: MCP_CREDITS_FEATURE_ID, value: 5 }),
+ ]);
+ });
+
+ it("records the allocation once, for 7 days, under the charge's key", async () => {
+ mcpBalance(3);
+
+ await new AutumnService().trackHostedMcpCredits(charge);
+
+ expect(redis.set).toHaveBeenCalledExactlyOnceWith(
+ "fc:mcp-credits:allocation:fc:track:scrape:job-1",
+ 3,
+ "EX",
+ 7 * 24 * 60 * 60,
+ "NX",
+ );
+ });
+
+ it("works the split out afresh for a charge without a key", async () => {
+ mcpBalance(3);
+
+ await new AutumnService().trackHostedMcpCredits({
+ ...charge,
+ idempotencyKey: undefined,
+ });
+
+ expect(redis.get).not.toHaveBeenCalled();
+ expect(redis.set).not.toHaveBeenCalled();
+ });
+
+ it("works the split out afresh when Redis hangs", async () => {
+ vi.useFakeTimers();
+ try {
+ mcpBalance(3);
+ redis.get.mockReturnValueOnce(new Promise<string | null>(() => {}));
+
+ const result = new AutumnService().trackHostedMcpCredits(charge);
+ await vi.advanceTimersByTimeAsync(1000);
+
+ expect(await result).toEqual({ tracked: true, mcpCredits: 3 });
+ } finally {
+ vi.useRealTimers();
+ }
+ });
+
+ it("works the split out afresh when Redis can't answer", async () => {
+ mcpBalance(3);
+ redis.get.mockRejectedValueOnce(new Error("redis down"));
+
+ expect(await new AutumnService().trackHostedMcpCredits(charge)).toEqual({
+ tracked: true,
+ mcpCredits: 3,
+ });
+ });
+});
diff --git a/apps/api/src/services/autumn/autumn.service.ts b/apps/api/src/services/autumn/autumn.service.ts
index 873c61352..e43685b28 100644
--- a/apps/api/src/services/autumn/autumn.service.ts
+++ b/apps/api/src/services/autumn/autumn.service.ts
@@ -19,6 +19,7 @@ import {
autumnEntityCreatedInlineTotal,
billingRouteTotal,
} from "./metrics";
+import { getRedisConnection } from "../queue-service";
import type {
CreateEntityParams,
CreateEntityResult,
@@ -37,6 +38,12 @@ import { ExistingCreditsLockError } from "./types";
export const TEAM_FEATURE_ID = "TEAM";
export const CREDITS_FEATURE_ID = "CREDITS";
export const SEARCH_CREDITS_FEATURE_ID = "SEARCH_CREDITS";
+/**
+ * The balance hosted MCP calls spend before the endpoint's own feature (see
+ * AutumnService.trackHostedMcpCredits). Configurable so the id can follow the
+ * Autumn feature without a code change.
+ */
+export const MCP_CREDITS_FEATURE_ID = config.MCP_CREDITS_FEATURE_ID;
const CONCURRENCY_FEATURE_ID = "CONCURRENCY";
const RATE_LIMIT_FEATURE_ID = "rate_limits";
@@ -567,6 +574,158 @@ export class AutumnService {
}
}
+ /**
+ * How much of a hosted MCP charge of `value` the team's MCP credits
+ * (MCP_CREDITS_FEATURE_ID) can pay: all of it, or what is left when that is
+ * less. 0 for a team without the feature or with none left, for a
+ * partner-provisioned team (its usage is split with the partner on the
+ * regular features), and when Autumn can't answer.
+ */
+ async mcpCreditsAvailable({
+ teamId,
+ orgId,
+ value,
+ properties,
+ }: Pick<
+ TrackCreditsParams,
+ "teamId" | "orgId" | "value" | "properties"
+ >): Promise<number> {
+ if (!(value > 0) || this.isPreviewTeam(teamId)) return 0;
+ if (await this.isGatewayProvisioned(teamId)) return 0;
+ const result = await this.checkCredits({
+ teamId,
+ orgId,
+ value,
+ properties,
+ featureId: MCP_CREDITS_FEATURE_ID,
+ });
+ if (!result) return 0;
+ if (result.allowed) return value;
+ return Math.max(0, Math.min(value, Math.floor(result.remaining)));
+ }
+
+ /**
+ * The MCP credits part of a keyed hosted MCP charge. The first attempt
+ * records it, so a retry under the same key (a stalled job re-running its
+ * charge) splits the charge the same way and each part dedupes against its
+ * first track, even after that first track used the MCP credits up. Without
+ * a key, or when Redis doesn't answer within a second, it is worked out
+ * afresh. The shared connection queues commands while Redis is down rather
+ * than failing them, hence the bound.
+ */
+ private async hostedMcpAllocation(params: TrackCreditsParams) {
+ if (!params.idempotencyKey) return this.mcpCreditsAvailable(params);
+ const key = `fc:mcp-credits:allocation:${params.idempotencyKey}`;
+ const redis = getRedisConnection();
+ const bounded = async <T>(command: Promise<T>): Promise<T> => {
+ let timer: NodeJS.Timeout | undefined;
+ try {
+ return await Promise.race([
+ command,
+ new Promise<never>((_, reject) => {
+ timer = setTimeout(
+ () => reject(new Error("Redis did not answer in time")),
+ 1000,
+ );
+ }),
+ ]);
+ } finally {
+ clearTimeout(timer);
+ }
+ };
+ try {
+ const recorded = await bounded(redis.get(key));
+ if (recorded !== null) return Number(recorded);
+ } catch (error) {
+ logger.warn("Failed to read a hosted MCP charge's allocation", {
+ key,
+ error,
+ });
+ return this.mcpCreditsAvailable(params);
+ }
+ const mcpCredits = await this.mcpCreditsAvailable(params);
+ try {
+ if (
+ (await bounded(
+ redis.set(key, mcpCredits, "EX", 7 * 24 * 60 * 60, "NX"),
+ )) === null
+ ) {
+ const recorded = await bounded(redis.get(key));
+ if (recorded !== null) return Number(recorded);
+ }
+ } catch (error) {
+ logger.warn("Failed to record a hosted MCP charge's allocation", {
+ key,
+ error,
+ });
+ }
+ return mcpCredits;
+ }
+
+ /**
+ * Tracks a hosted MCP charge: the part the team's MCP credits can pay (see
+ * mcpCreditsAvailable) on MCP_CREDITS_FEATURE_ID, and the rest on
+ * `featureId`, the endpoint's own feature. When the MCP credits pay nothing,
+ * the whole charge is tracked exactly as trackCredits would track it.
+ * Resolves whether every part was tracked, and the credits tracked on
+ * MCP_CREDITS_FEATURE_ID: those were charged even when `tracked` is false,
+ * so a caller reversing the charge reverses them on their own.
+ */
+ async trackHostedMcpCredits(
+ params: TrackCreditsParams,
+ ): Promise<{ tracked: boolean; mcpCredits: number }> {
+ const mcpCredits = await this.hostedMcpAllocation(params);
+ const rest = params.value - mcpCredits;
+ const [mcpTracked, restTracked] = await Promise.all([
+ mcpCredits > 0
+ ? this.trackCredits({
+ ...params,
+ value: mcpCredits,
+ featureId: MCP_CREDITS_FEATURE_ID,
+ // Its own charge event: the rest keeps the caller's key, and the
+ // same key would dedupe one part against the other.
+ idempotencyKey:
+ params.idempotencyKey && `${params.idempotencyKey}:mcp`,
+ })
+ : true,
+ mcpCredits === 0 || rest > 0
+ ? this.trackCredits({ ...params, value: rest })
+ : true,
+ ]);
+ return {
+ tracked: mcpTracked && restTracked,
+ mcpCredits: mcpTracked ? mcpCredits : 0,
+ };
+ }
+
+ /**
+ * Reverses a trackHostedMcpCredits charge: `mcpCredits` back to
+ * MCP_CREDITS_FEATURE_ID and the rest to `featureId`, each part keyed as it
+ * was tracked. With no MCP credits it is exactly refundCredits. Resolves
+ * whether every part was refunded.
+ */
+ async refundHostedMcpCredits({
+ mcpCredits,
+ ...params
+ }: TrackCreditsParams & { mcpCredits: number }): Promise<boolean> {
+ const rest = params.value - mcpCredits;
+ const [mcpRefunded, restRefunded] = await Promise.all([
+ mcpCredits > 0
+ ? this.refundCredits({
+ ...params,
+ value: mcpCredits,
+ featureId: MCP_CREDITS_FEATURE_ID,
+ idempotencyKey:
+ params.idempotencyKey && `${params.idempotencyKey}:mcp`,
+ })
+ : true,
+ mcpCredits === 0 || rest > 0
+ ? this.refundCredits({ ...params, value: rest })
+ : true,
+ ]);
+ return mcpRefunded && restRefunded;
+ }
+
/**
* Whether the org has an auto top-up that can actually fire for CREDITS: it
* is enabled, and the org holds a prepaid CREDITS item for it to buy. Autumn
diff --git a/apps/api/src/services/billing/__tests__/batch_billing.test.ts b/apps/api/src/services/billing/__tests__/batch_billing.test.ts
index 69432224a..d1b41827e 100644
--- a/apps/api/src/services/billing/__tests__/batch_billing.test.ts
+++ b/apps/api/src/services/billing/__tests__/batch_billing.test.ts
@@ -10,6 +10,7 @@ const {
refundCredits,
billTeam7,
getACUCTeam,
+ reportExchangeBilling,
} = vi.hoisted(() => {
const logger: any = {
info: vi.fn(),
@@ -24,9 +25,14 @@ const {
refundCredits: vi.fn<(args: any) => Promise<void>>(),
billTeam7: vi.fn<(params: any) => Promise<{ api_key: string }[]>>(),
getACUCTeam: vi.fn<(teamId: string) => Promise<any>>(),
+ reportExchangeBilling: vi.fn<(args: any) => Promise<boolean>>(),
};
});
+vi.mock("../../../lib/exchange", () => ({
+ reportExchangeBilling,
+}));
+
vi.mock("../../../lib/logger", () => ({
logger,
}));
@@ -42,6 +48,7 @@ vi.mock("../../autumn/autumn.service", () => ({
},
featureIdForBillingEndpoint: (endpoint?: string) =>
endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",
+ MCP_CREDITS_FEATURE_ID: "MCP_CREDITS",
}));
vi.mock("../../../db/rpc", () => ({
@@ -120,6 +127,7 @@ vi.mock("../../queue-service", () => ({
import {
processBillingBatch,
+ queueBillingOperation,
startBillingBatchProcessing,
} from "../batch_billing";
@@ -428,3 +436,150 @@ describe("startBillingBatchProcessing", () => {
expect(queue).toHaveLength(0);
});
});
+
+describe("MCP credits on the ledger", () => {
+ it("records the part MCP credits paid as its own tagged row", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },
+ false,
+ true,
+ );
+ expect(queue).toHaveLength(1);
+
+ await processBillingBatch();
+
+ expect(billTeam7).toHaveBeenCalledTimes(2);
+ expect(billTeam7).toHaveBeenCalledWith(
+ expect.objectContaining({ credits: 2, subscription_id: null }),
+ );
+ expect(billTeam7).toHaveBeenCalledWith(
+ expect.objectContaining({ credits: 3, subscription_id: "mcp_credits" }),
+ );
+ });
+
+ it("records a charge MCP credits paid in full as one tagged row", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 5 },
+ false,
+ true,
+ );
+ await processBillingBatch();
+
+ expect(billTeam7).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ credits: 5, subscription_id: "mcp_credits" }),
+ );
+ });
+
+ it("records a charge MCP credits paid nothing of as today's untagged row", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true },
+ false,
+ true,
+ );
+ await processBillingBatch();
+
+ expect(billTeam7).toHaveBeenCalledExactlyOnceWith({
+ team_id: "team-1",
+ subscription_id: null,
+ credits: 5,
+ api_key_id: 123,
+ is_extract: false,
+ });
+ });
+
+ it("refunds each part to the balance it was tracked on when the ledger fails", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },
+ false,
+ true,
+ );
+ billTeam7.mockRejectedValue(new Error("db failed"));
+
+ await processBillingBatch();
+
+ expect(refundCredits).toHaveBeenCalledTimes(2);
+ expect(refundCredits).toHaveBeenCalledWith(
+ expect.objectContaining({ value: 2, featureId: "CREDITS" }),
+ );
+ expect(refundCredits).toHaveBeenCalledWith(
+ expect.objectContaining({ value: 3, featureId: "MCP_CREDITS" }),
+ );
+ });
+
+ it("refunds only the MCP credits part when the rest was not tracked", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },
+ false,
+ false,
+ );
+ billTeam7.mockRejectedValue(new Error("db failed"));
+
+ await processBillingBatch();
+
+ expect(refundCredits).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ value: 3, featureId: "MCP_CREDITS" }),
+ );
+ });
+
+ it("confirms a split charge's Exchange access once, after both rows commit", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },
+ false,
+ true,
+ { accessEventId: "access-1", billingReference: "ref-1" },
+ );
+ await processBillingBatch();
+
+ expect(reportExchangeBilling).toHaveBeenCalledExactlyOnceWith({
+ accessEventId: "access-1",
+ status: "confirmed",
+ billingReference: "ref-1",
+ });
+ });
+
+ it("leaves a split charge's Exchange access pending when one row fails", async () => {
+ await queueBillingOperation(
+ "team-1",
+ "org-1",
+ 5,
+ 123,
+ { endpoint: "scrape", hostedMcp: true, mcpCredits: 3 },
+ false,
+ true,
+ { accessEventId: "access-1" },
+ );
+ billTeam7.mockImplementation(async ({ subscription_id }) => {
+ if (subscription_id === "mcp_credits") throw new Error("db failed");
+ return [];
+ });
+
+ await processBillingBatch();
+
+ expect(billTeam7).toHaveBeenCalledTimes(2);
+ expect(reportExchangeBilling).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/api/src/services/billing/__tests__/credit_billing.test.ts b/apps/api/src/services/billing/__tests__/credit_billing.test.ts
index c5ad2c54c..a54e0b288 100644
--- a/apps/api/src/services/billing/__tests__/credit_billing.test.ts
+++ b/apps/api/src/services/billing/__tests__/credit_billing.test.ts
@@ -7,6 +7,8 @@ const {
trackCredits,
refundCredits,
isRoutedThroughFirebill,
+ trackHostedMcpCredits,
+ refundHostedMcpCredits,
} = vi.hoisted(() => ({
withAuth: vi.fn((fn: any) => fn),
queueBillingOperation: vi.fn<(args: any[]) => Promise<any>>(),
@@ -14,6 +16,9 @@ const {
refundCredits: vi.fn<(args: any) => Promise<void>>(),
isRoutedThroughFirebill:
vi.fn<(teamId: string, orgId: string) => Promise<boolean>>(),
+ trackHostedMcpCredits:
+ vi.fn<(args: any) => Promise<{ tracked: boolean; mcpCredits: number }>>(),
+ refundHostedMcpCredits: vi.fn<(args: any) => Promise<boolean>>(),
}));
vi.mock("../../../lib/withAuth", () => ({
@@ -29,6 +34,8 @@ vi.mock("../../autumn/autumn.service", () => ({
trackCredits,
refundCredits,
isRoutedThroughFirebill,
+ trackHostedMcpCredits,
+ refundHostedMcpCredits,
},
featureIdForBillingEndpoint: (endpoint?: string) =>
endpoint === "search" ? "SEARCH_CREDITS" : "CREDITS",
@@ -57,6 +64,7 @@ beforeEach(() => {
trackCredits.mockResolvedValue(true);
refundCredits.mockResolvedValue(undefined);
isRoutedThroughFirebill.mockResolvedValue(false);
+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 0 });
});
describe("billTeam", () => {
@@ -231,3 +239,140 @@ describe("billTeam", () => {
expect(refundCredits).not.toHaveBeenCalled();
});
});
+
+describe("billTeam MCP credits", () => {
+ const hostedMcpScrape = {
+ endpoint: "scrape" as const,
+ jobId: "job-1",
+ chargeId: "job-1",
+ hostedMcp: true,
+ };
+
+ it("charges a hosted MCP call through the MCP credits split", async () => {
+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 2 });
+
+ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);
+
+ expect(trackHostedMcpCredits).toHaveBeenCalledExactlyOnceWith({
+ teamId: "team-1",
+ orgId: "org-1",
+ value: 3,
+ properties: {
+ source: "billTeam",
+ endpoint: "scrape",
+ jobId: "job-1",
+ apiKeyId: 123,
+ },
+ featureId: "CREDITS",
+ idempotencyKey: "fc:track:scrape:job-1",
+ externalRequestId: undefined,
+ });
+ expect(trackCredits).not.toHaveBeenCalled();
+ // The ledger records the MCP-paid part apart from regular credits.
+ expect(queueBillingOperation).toHaveBeenCalledWith([
+ "team-1",
+ "org-1",
+ 3,
+ 123,
+ { ...hostedMcpScrape, mcpCredits: 2 },
+ false,
+ true,
+ ]);
+ });
+
+ it("queues an unchanged ledger operation when MCP credits paid nothing", async () => {
+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 0 });
+
+ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);
+
+ expect(queueBillingOperation).toHaveBeenCalledWith([
+ "team-1",
+ "org-1",
+ 3,
+ 123,
+ hostedMcpScrape,
+ false,
+ true,
+ ]);
+ });
+
+ it("refunds a failed enqueue to the balances the charge was tracked on", async () => {
+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 2 });
+ queueBillingOperation.mockResolvedValueOnce({ success: false });
+
+ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);
+
+ expect(refundHostedMcpCredits).toHaveBeenCalledExactlyOnceWith({
+ teamId: "team-1",
+ orgId: "org-1",
+ value: 3,
+ mcpCredits: 2,
+ properties: {
+ source: "billTeam",
+ endpoint: "scrape",
+ jobId: "job-1",
+ apiKeyId: 123,
+ },
+ featureId: "CREDITS",
+ idempotencyKey: "fc:refund:scrape:job-1",
+ externalRequestId: undefined,
+ });
+ expect(refundCredits).not.toHaveBeenCalled();
+ });
+
+ it("refunds the MCP credits part of a failed enqueue even when the rest was not tracked", async () => {
+ trackHostedMcpCredits.mockResolvedValue({ tracked: false, mcpCredits: 2 });
+ queueBillingOperation.mockResolvedValueOnce({ success: false });
+
+ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);
+
+ expect(queueBillingOperation).toHaveBeenCalledWith(
+ expect.arrayContaining([false]),
+ );
+ expect(refundHostedMcpCredits).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ value: 2, mcpCredits: 2 }),
+ );
+ expect(refundCredits).not.toHaveBeenCalled();
+ });
+
+ it("refunds nothing for a failed enqueue when nothing was tracked", async () => {
+ trackHostedMcpCredits.mockResolvedValue({ tracked: false, mcpCredits: 0 });
+ queueBillingOperation.mockResolvedValueOnce({ success: false });
+
+ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);
+
+ expect(refundHostedMcpCredits).not.toHaveBeenCalled();
+ expect(refundCredits).not.toHaveBeenCalled();
+ });
+
+ it("refunds a failed enqueue MCP credits paid nothing of as today", async () => {
+ trackHostedMcpCredits.mockResolvedValue({ tracked: true, mcpCredits: 0 });
+ queueBillingOperation.mockResolvedValueOnce({ success: false });
+
+ await billTeam("team-1", "org-1", 3, 123, hostedMcpScrape);
+
+ expect(refundCredits).toHaveBeenCalledWith(
+ expect.objectContaining({ value: 3, featureId: "CREDITS" }),
+ );
+ expect(refundHostedMcpCredits).not.toHaveBeenCalled();
+ });
+
+ it("never goes through the MCP credits split for a call the hosted MCP did not make", async () => {
+ await billTeam("team-1", "org-1", 3, 123, {
+ endpoint: "scrape",
+ jobId: "job-1",
+ });
+
+ expect(trackHostedMcpCredits).not.toHaveBeenCalled();
+ expect(trackCredits).toHaveBeenCalledWith(
+ expect.objectContaining({ featureId: "CREDITS" }),
+ );
+ });
+
+ it("never charges Autumn for a team without an org", async () => {
+ await billTeam("preview_abc", null, 3, null, hostedMcpScrape);
+
+ expect(trackHostedMcpCredits).not.toHaveBeenCalled();
+ expect(trackCredits).not.toHaveBeenCalled();
+ });
+});
diff --git a/apps/api/src/services/billing/batch_billing.ts b/apps/api/src/services/billing/batch_billing.ts
index 0fbb35c6d..4e8d57c8d 100644
--- a/apps/api/src/services/billing/batch_billing.ts
+++ b/apps/api/src/services/billing/batch_billing.ts
@@ -5,6 +5,7 @@ import { withAuth } from "../../lib/withAuth";
import {
autumnService,
featureIdForBillingEndpoint,
+ MCP_CREDITS_FEATURE_ID,
} from "../autumn/autumn.service";
import {
resolveBillingMetadata,
@@ -83,6 +84,9 @@ const BATCH_LOCK_KEY = "billing_batch_lock";
const BATCH_SIZE = 5000; // Batch size for processing
const BATCH_TIMEOUT = 15000; // 15 seconds processing interval
const LOCK_TIMEOUT = 30000; // 30 seconds lock timeout
+// The ledger's tag for usage the team's MCP credits paid. bill_team_7 stores it
+// in credit_usage.subscription_id, which it passes through as a tag.
+const MCP_CREDITS_LEDGER_TAG = "mcp_credits";
// Define interfaces for billing operations
interface BillingOperation {
@@ -115,6 +119,7 @@ interface GroupedBillingOperation {
billing: BillingMetadata;
is_extract: boolean;
api_key_id: number | null;
+ ledger_tag?: string;
operations: BillingOperation[];
}
@@ -186,7 +191,11 @@ async function refundRequestTrackedCredits(
...toAutumnBillingProperties(group.billing),
apiKeyId: group.api_key_id,
},
- featureId: featureIdForBillingEndpoint(group.billing.endpoint),
+ // The part MCP credits paid goes back to them.
+ featureId:
+ group.ledger_tag === MCP_CREDITS_LEDGER_TAG
+ ? MCP_CREDITS_FEATURE_ID
+ : featureIdForBillingEndpoint(group.billing.endpoint),
});
} catch (error) {
logger.warn("Failed to refund Autumn request-tracked credits", {
@@ -211,8 +220,11 @@ export async function processBillingBatch() {
}
// Exchange operations whose debit committed this run; their ledger
- // confirmations are delivered after the lock is released.
+ // confirmations are delivered after the lock is released. An operation
+ // MCP credits paid part of is split across ledger rows, so each access
+ // counts the rows it spans.
const committedExchangeOps: BillingOperation[] = [];
+ const exchangeRowCounts = new Map<string, number>();
try {
// Get all operations from Redis list
@@ -287,23 +299,51 @@ export async function processBillingBatch() {
} else {
orgId = op.org_id;
}
- const key = `${op.team_id}:${orgId}:${billing.endpoint}:${op.is_extract}:${op.api_key_id}`;
-
- if (!groupedOperations.has(key)) {
- groupedOperations.set(key, {
- team_id: op.team_id,
- org_id: orgId,
- total_credits: 0,
- billing,
- is_extract: op.is_extract,
- api_key_id: op.api_key_id,
- operations: [],
- });
+ // The part the team's MCP credits paid is its own ledger row, tagged so
+ // MCP-paid usage is counted apart from regular credits used.
+ const mcpCredits = Math.min(billing.mcpCredits ?? 0, op.credits);
+ const parts = [
+ ...(mcpCredits === 0 || mcpCredits < op.credits
+ ? [{ credits: op.credits - mcpCredits, ledger_tag: undefined }]
+ : []),
+ ...(mcpCredits > 0
+ ? [{ credits: mcpCredits, ledger_tag: MCP_CREDITS_LEDGER_TAG }]
+ : []),
+ ];
+ if (op.exchange_access_event_id !== undefined) {
+ exchangeRowCounts.set(
+ op.exchange_access_event_id,
+ (exchangeRowCounts.get(op.exchange_access_event_id) ?? 0) +
+ parts.length,
+ );
}
+ for (const { credits, ledger_tag } of parts) {
+ const key = `${op.team_id}:${orgId}:${billing.endpoint}:${ledger_tag ?? ""}:${op.is_extract}:${op.api_key_id}`;
+
+ if (!groupedOperations.has(key)) {
+ groupedOperations.set(key, {
+ team_id: op.team_id,
+ org_id: orgId,
+ total_credits: 0,
+ billing,
+ is_extract: op.is_extract,
+ api_key_id: op.api_key_id,
+ ledger_tag,
+ operations: [],
+ });
+ }
- const group = groupedOperations.get(key)!;
- group.total_credits += op.credits;
- group.operations.push(op);
+ const group = groupedOperations.get(key)!;
+ group.total_credits += credits;
+ // MCP credits are only recorded once their track succeeded, so their
+ // row is refundable even when the rest of the charge was not tracked.
+ group.operations.push({
+ ...op,
+ credits,
+ autumnTrackInRequest:
+ ledger_tag === MCP_CREDITS_LEDGER_TAG || op.autumnTrackInRequest,
+ });
+ }
}
if (unresolvedOperations.length > 0) {
@@ -350,6 +390,7 @@ export async function processBillingBatch() {
group.api_key_id,
logger,
group.is_extract,
+ group.ledger_tag ?? null,
);
if (!billingResult.success) {
@@ -401,7 +442,23 @@ export async function processBillingBatch() {
await releaseLock();
}
- await confirmExchangeOutcomes(committedExchangeOps);
+ // An access is confirmed once, and only after every row it spans committed.
+ const committedRows = new Map<string, BillingOperation[]>();
+ for (const op of committedExchangeOps) {
+ const accessEventId = op.exchange_access_event_id!;
+ committedRows.set(accessEventId, [
+ ...(committedRows.get(accessEventId) ?? []),
+ op,
+ ]);
+ }
+ await confirmExchangeOutcomes(
+ [...committedRows]
+ .filter(
+ ([accessEventId, rows]) =>
+ rows.length === exchangeRowCounts.get(accessEventId),
+ )
+ .map(([, rows]) => rows[0]),
+ );
}
// Start periodic batch processing
@@ -515,6 +572,7 @@ async function supaBillTeam(
api_key_id: number | null,
__logger?: any,
is_extract: boolean = false,
+ subscription_id: string | null = null,
) {
const _logger = (__logger ?? logger).child({
module: "credit_billing",
@@ -534,7 +592,7 @@ async function supaBillTeam(
try {
data = await billTeam7({
team_id,
- subscription_id: null,
+ subscription_id,
credits,
api_key_id: api_key_id ?? null,
is_extract,
diff --git a/apps/api/src/services/billing/credit_billing.ts b/apps/api/src/services/billing/credit_billing.ts
index a8d54da0a..6aefa9c10 100644
--- a/apps/api/src/services/billing/credit_billing.ts
+++ b/apps/api/src/services/billing/credit_billing.ts
@@ -40,10 +40,11 @@ export async function billTeam(
const featureId = featureIdForBillingEndpoint(billing.endpoint);
let trackedInRequest = false;
+ let mcpCredits = 0;
if (org_id !== null) {
// Stable per-charge key (firebill route only): a caller retry or re-run
// job with the same chargeId dedupes instead of double-billing.
- trackedInRequest = await autumnService.trackCredits({
+ const charge = {
teamId: team_id,
orgId: org_id,
value: credits,
@@ -53,7 +54,14 @@ export async function billTeam(
? `fc:track:${billing.endpoint}:${billing.chargeId}`
: undefined,
externalRequestId: billing.externalRequestId ?? undefined,
- });
+ };
+ // A hosted MCP charge spends the team's MCP credits first.
+ if (billing.hostedMcp) {
+ ({ tracked: trackedInRequest, mcpCredits } =
+ await autumnService.trackHostedMcpCredits(charge));
+ } else {
+ trackedInRequest = await autumnService.trackCredits(charge);
+ }
} else if (team_id !== "preview" && !team_id.startsWith("preview_")) {
// Preview teams are never tracked anyway; a real team arriving without
// an org is not expected, and its usage is about to go unmetered.
@@ -68,13 +76,19 @@ export async function billTeam(
org_id,
credits,
api_key_id,
- billing,
+ mcpCredits > 0 ? { ...billing, mcpCredits } : billing,
false,
trackedInRequest,
);
// A track only happens with an org in hand; named again so the type says so.
- if (!result.success && trackedInRequest && org_id !== null) {
+ // A charge the MCP credits paid part of is refundable for that part even
+ // when the rest was not tracked.
+ if (
+ !result.success &&
+ (trackedInRequest || mcpCredits > 0) &&
+ org_id !== null
+ ) {
if (await autumnService.isRoutedThroughFirebill(team_id, org_id)) {
// No compensating refund on the firebill route: the tracked charge
// is durable and correct, and a refund here poisons a retried
@@ -86,10 +100,12 @@ export async function billTeam(
{ team_id, credits, billing },
);
} else {
- await autumnService.refundCredits({
+ const refund = {
teamId: team_id,
orgId: org_id,
- value: credits,
+ // Only what was charged: the rest when it was tracked, and the
+ // MCP credits part (refunded on its own below).
+ value: (trackedInRequest ? credits - mcpCredits : 0) + mcpCredits,
properties: autumnProperties,
featureId,
// Distinct from the track key: the refund is its own charge event.
@@ -97,7 +113,11 @@ export async function billTeam(
? `fc:refund:${billing.endpoint}:${billing.chargeId}`
: undefined,
externalRequestId: billing.externalRequestId ?? undefined,
- });
+ };
+ // A split charge refunds each part to the balance it was tracked on.
+ await (mcpCredits > 0
+ ? autumnService.refundHostedMcpCredits({ ...refund, mcpCredits })
+ : autumnService.refundCredits(refund));
}
}
diff --git a/apps/api/src/services/billing/types.ts b/apps/api/src/services/billing/types.ts
index 2b078a1fe..6c63d9732 100644
--- a/apps/api/src/services/billing/types.ts
+++ b/apps/api/src/services/billing/types.ts
@@ -39,6 +39,19 @@ export type BillingMetadata = {
* Unset when the caller sent no header or the charge has no request.
*/
externalRequestId?: string | null;
+ /**
+ * The hosted MCP made the request, as verified at authentication (see
+ * `AuthObject.hostedMcp`). Its charges spend the team's MCP credits first
+ * (see AutumnService.trackHostedMcpCredits). Rides the job payload like the
+ * rest of this metadata, so a crawl's pages carry it too.
+ */
+ hostedMcp?: boolean;
+ /**
+ * Credits of this charge the team's MCP credits paid, set by the charge that
+ * tracks them to Autumn (billTeam or billScrapeJob). The ledger records them as their own row, tagged apart from
+ * regular credits used (see queueBillingOperation).
+ */
+ mcpCredits?: number;
};
export function resolveBillingMetadata({
diff --git a/apps/api/src/services/worker/scrape-worker.ts b/apps/api/src/services/worker/scrape-worker.ts
index 64b4b3602..80ba0c14e 100644
--- a/apps/api/src/services/worker/scrape-worker.ts
+++ b/apps/api/src/services/worker/scrape-worker.ts
@@ -171,6 +171,7 @@ async function billScrapeJob(
// request's own credits. Standalone scrapes stay on CREDITS.
const featureId = featureIdForBillingEndpoint(billing.endpoint);
let trackedInRequest = false;
+ let mcpCredits = 0;
if (job.data.is_scrape !== true && !job.data.internalOptions?.bypassBilling) {
creditsToBeBilled = await calculateCreditsToBeBilled(
@@ -209,24 +210,31 @@ async function billScrapeJob(
routedToFirebill = orgId
? await autumnService.isRoutedThroughFirebill(job.data.team_id, orgId)
: false;
- trackedInRequest = orgId
- ? await autumnService.trackCredits({
- teamId: job.data.team_id,
- orgId,
- value: creditsToBeBilled,
- properties: autumnProperties,
- featureId,
- // The worker job id is the one identity that is unique per charge
- // (a crawl id is shared by every page β€” keying on it would collapse
- // a crawl's pages into one billed event) AND survives a stall
- // requeue, which re-runs the job under the same id: with this key,
- // the re-run dedupes instead of double-billing (firebill route).
- idempotencyKey: `fc:track:${billing.endpoint}:${job.id}`,
- // The caller's own operation id, carried on the charge so
- // firebill reports it without a request lookup.
- externalRequestId: billing.externalRequestId ?? undefined,
- })
- : false;
+ if (orgId) {
+ const charge = {
+ teamId: job.data.team_id,
+ orgId,
+ value: creditsToBeBilled,
+ properties: autumnProperties,
+ featureId,
+ // The worker job id is the one identity that is unique per charge
+ // (a crawl id is shared by every page β€” keying on it would collapse
+ // a crawl's pages into one billed event) AND survives a stall
+ // requeue, which re-runs the job under the same id: with this key,
+ // the re-run dedupes instead of double-billing (firebill route).
+ idempotencyKey: `fc:track:${billing.endpoint}:${job.id}`,
+ // The caller's own operation id, carried on the charge so
+ // firebill reports it without a request lookup.
+ externalRequestId: billing.externalRequestId ?? undefined,
+ };
+ // A hosted MCP charge spends the team's MCP credits first.
+ if (billing.hostedMcp) {
+ ({ tracked: trackedInRequest, mcpCredits } =
+ await autumnService.trackHostedMcpCredits(charge));
+ } else {
+ trackedInRequest = await autumnService.trackCredits(charge);
+ }
+ }
// On the firebill route the ledger enqueue must be idempotent by the
// originating job: a stalled job reruns under the same job.id, the
// track dedupes in firebill, and a fresh random billing job id would
@@ -265,7 +273,7 @@ async function billScrapeJob(
team_id: job.data.team_id,
org_id: orgId,
credits: creditsToBeBilled,
- billing,
+ billing: mcpCredits > 0 ? { ...billing, mcpCredits } : billing,
is_extract: false,
timestamp: new Date().toISOString(),
originating_job_id: job.id,
@@ -298,7 +306,10 @@ async function billScrapeJob(
`Failed to add billing job to queue for team ${job.data.team_id} for ${creditsToBeBilled} credits`,
{ error },
);
- if (trackedInRequest && creditsToBeBilled !== null) {
+ if (
+ (trackedInRequest || mcpCredits > 0) &&
+ creditsToBeBilled !== null
+ ) {
if (routedToFirebill) {
// No compensating refund on the firebill route: the tracked charge
// is durable and correct (the scrape ran), and refunding it here
@@ -319,17 +330,25 @@ async function billScrapeJob(
},
);
} else if (orgId) {
- await autumnService.refundCredits({
+ const refund = {
teamId: job.data.team_id,
orgId,
- value: creditsToBeBilled,
+ // Only what was charged: the rest when it was tracked, and the
+ // MCP credits part (refunded on its own below).
+ value:
+ (trackedInRequest ? creditsToBeBilled - mcpCredits : 0) +
+ mcpCredits,
properties: autumnProperties,
featureId,
// Distinct from the track key: a refund is its own charge event
// (same key would 409 as a duplicate of the track and be dropped).
idempotencyKey: `fc:refund:${billing.endpoint}:${job.id}`,
externalRequestId: billing.externalRequestId ?? undefined,
- });
+ };
+ // A split charge refunds each part to the balance it was tracked on.
+ await (mcpCredits > 0
+ ? autumnService.refundHostedMcpCredits({ ...refund, mcpCredits })
+ : autumnService.refundCredits(refund));
}
}
// The billing operation never reached the queue, so no debit will
diff --git a/apps/api/src/types.ts b/apps/api/src/types.ts
index 85c4a81c7..a5a0d38fb 100644
--- a/apps/api/src/types.ts
+++ b/apps/api/src/types.ts
@@ -172,6 +172,8 @@ export type AuthResponse =
org_id?: string | null;
api_key?: string;
chunk: AuthCreditUsageChunk | null;
+ // The hosted MCP made the call, as verified in supaAuthenticateUser.
+ hostedMcp?: boolean;
}
| {
success: false;