Skip to content

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

fix(billing): let hosted MCP calls fall back to team-scoped credits (#5528)

Gaurav Chadha6b02a6cdb9d9
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 422327af0..43c1d2e5f 100644
--- a/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
+++ b/apps/api/src/__tests__/routes/check-credits-middleware.test.ts
@@ -463,9 +463,10 @@ describe("checkCreditsMiddleware – MCP credits", () => {
expect(nextCalled).toBe(false);
});
- it("clamps the crawl limit against MCP credits on the re-check too", async () => {
+ it("clamps the crawl limit against MCP credits when the team's credits can't cover it either", async () => {
checkCreditsMock
.mockResolvedValueOnce({ allowed: false, remaining: 5 })
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
.mockResolvedValueOnce({ allowed: true, remaining: 5 });
const req = buildReq({ auth: hostedMcpAuth, body: { limit: 100 } });
@@ -473,10 +474,91 @@ describe("checkCreditsMiddleware – MCP credits", () => {
expect(res.status).not.toHaveBeenCalled();
expect(req.body.limit).toBe(5);
- expect(checkCreditsMock).toHaveBeenCalledTimes(2);
- for (const [check] of checkCreditsMock.mock.calls) {
- expect(check.featureId).toBe("MCP_CREDITS");
- }
+ expect(req.auth.hostedMcp).toBe(true);
+ expect(
+ checkCreditsMock.mock.calls.map(([check]) => check.featureId),
+ ).toEqual(["MCP_CREDITS", "CREDITS", "MCP_CREDITS"]);
+ });
+
+ it("clamps the crawl limit against the team's credits when they cover more", async () => {
+ checkCreditsMock
+ .mockResolvedValueOnce({ allowed: false, remaining: 5 })
+ .mockResolvedValueOnce({ allowed: false, remaining: 40 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 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(40);
+ expect(req.auth.hostedMcp).toBe(false);
+ expect(
+ checkCreditsMock.mock.calls.map(([check]) => check.featureId),
+ ).toEqual(["MCP_CREDITS", "CREDITS", "CREDITS"]);
+ });
+
+ it("falls back to the MCP clamp when the team clamp is refused", async () => {
+ checkCreditsMock
+ .mockResolvedValueOnce({ allowed: false, remaining: 5 })
+ .mockResolvedValueOnce({ allowed: false, remaining: 40 })
+ .mockResolvedValueOnce({ allowed: false, remaining: 40 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 5 });
+
+ 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);
+ expect(req.auth.hostedMcp).toBe(true);
+ expect(
+ checkCreditsMock.mock.calls.map(([check]) => check.featureId),
+ ).toEqual(["MCP_CREDITS", "CREDITS", "CREDITS", "MCP_CREDITS"]);
+ expect(checkCreditsMock.mock.calls[2][0].value).toBe(40);
+ expect(checkCreditsMock.mock.calls[3][0].value).toBe(5);
+ });
+
+ it("keeps the MCP refusal when the team-credit check can't be answered", async () => {
+ checkCreditsMock
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce(null);
+
+ const req = buildReq({ auth: { ...hostedMcpAuth } });
+ const { res, nextCalled } = await runMiddleware(req, spendsMcpCredits);
+
+ expect(res.status).toHaveBeenCalledWith(402);
+ expect(nextCalled).toBe(false);
+ expect(
+ checkCreditsMock.mock.calls.map(([check]) => check.featureId),
+ ).toEqual(["MCP_CREDITS", "CREDITS"]);
+ });
+
+ it("bills a hosted MCP call on the team's own credits when MCP credits can't cover it", async () => {
+ checkCreditsMock
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 200000 });
+
+ 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.auth.hostedMcp).toBe(false);
+ expect(checkCreditsMock.mock.calls[1][0]).toMatchObject({
+ teamId: "team_test",
+ value: 1,
+ featureId: "CREDITS",
+ });
});
it("gates a call the hosted MCP did not make on the route's own feature", async () => {
diff --git a/apps/api/src/controllers/v1/types.ts b/apps/api/src/controllers/v1/types.ts
index f7fc262bc..6d8a199ba 100644
--- a/apps/api/src/controllers/v1/types.ts
+++ b/apps/api/src/controllers/v1/types.ts
@@ -1320,6 +1320,7 @@ type AuthObject = {
agentInterop?: AgentInteropStatus;
// Set only by authMiddleware, from the hosted MCP verification in
// supaAuthenticateUser; never from the request body or headers directly.
+ // A credit gate clears it when the call is billed on the team's own credits.
hostedMcp?: boolean;
};
diff --git a/apps/api/src/controllers/v2/__tests__/agent-credit-gate.test.ts b/apps/api/src/controllers/v2/__tests__/agent-credit-gate.test.ts
index 44013c43a..8a8b80a3b 100644
--- a/apps/api/src/controllers/v2/__tests__/agent-credit-gate.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/agent-credit-gate.test.ts
@@ -230,10 +230,39 @@ describe("gateAgentCredits for a hosted MCP run", () => {
}
});
- it("refuses like any run when the check refuses", async () => {
- checkCredits.mockResolvedValueOnce({ allowed: false, remaining: 0 });
+ it("gates a run MCP credits can't cover on the team's own credits", async () => {
+ checkCredits
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 300 })
+ .mockResolvedValueOnce({ allowed: false, remaining: 300 });
+
+ expect(await hostedGate(1000)).toEqual({
+ allowed: true,
+ maxCredits: 300,
+ stopOnInsufficientCredits: true,
+ onTeamCredits: true,
+ });
+ expect(checkCredits.mock.calls.map(([check]) => check.featureId)).toEqual([
+ "MCP_CREDITS",
+ "CREDITS",
+ "CREDITS",
+ ]);
+ });
+
+ it("keeps the MCP refusal when the team-credit check can't be answered", async () => {
+ checkCredits
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce(null);
+
+ expect(await hostedGate(1000)).toEqual({ allowed: false, balance: 0 });
+ });
+
+ it("refuses like any run when both checks refuse, reporting the team's balance", async () => {
+ checkCredits
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce({ allowed: false, remaining: 4 });
- expect(await hostedGate()).toEqual({ allowed: false, balance: 0 });
+ expect(await hostedGate()).toEqual({ allowed: false, balance: 4 });
});
it("leaves the feature to the default for a run the hosted MCP did not start", async () => {
diff --git a/apps/api/src/controllers/v2/__tests__/browser-mcp-credits.test.ts b/apps/api/src/controllers/v2/__tests__/browser-mcp-credits.test.ts
index a45a636c4..91592e84b 100644
--- a/apps/api/src/controllers/v2/__tests__/browser-mcp-credits.test.ts
+++ b/apps/api/src/controllers/v2/__tests__/browser-mcp-credits.test.ts
@@ -3,6 +3,8 @@ import type { Response } from "express";
const mocks = vi.hoisted(() => ({
checkCredits: vi.fn(),
markHostedMcp: vi.fn(),
+ clearHostedMcp: vi.fn(),
+ markUsedPrompt: vi.fn(),
cameFromHostedMcp: vi.fn(),
usedPrompt: vi.fn(),
settleOnce: vi.fn(),
@@ -81,8 +83,9 @@ vi.mock("../../../lib/browser-sessions", () => ({
),
listUnsettledHangarSessions: vi.fn(),
didBrowserSessionUsePrompt: mocks.usedPrompt,
- markBrowserSessionUsedPrompt: vi.fn(),
+ markBrowserSessionUsedPrompt: mocks.markUsedPrompt,
markBrowserSessionHostedMcp: mocks.markHostedMcp,
+ clearBrowserSessionHostedMcp: mocks.clearHostedMcp,
didBrowserSessionComeFromHostedMcp: mocks.cameFromHostedMcp,
upsertBrowserProfile: vi.fn(),
deleteBrowserProfile: vi.fn(),
@@ -176,6 +179,7 @@ beforeEach(() => {
vi.clearAllMocks();
mocks.checkCredits.mockResolvedValue({ allowed: true, remaining: 1000 });
mocks.markHostedMcp.mockResolvedValue(undefined);
+ mocks.clearHostedMcp.mockResolvedValue(undefined);
mocks.cameFromHostedMcp.mockResolvedValue(false);
mocks.usedPrompt.mockResolvedValue(false);
mocks.billTeam.mockResolvedValue({ success: true });
@@ -205,6 +209,18 @@ describe("browser sessions from hosted MCP calls", () => {
expect(mocks.markHostedMcp).not.toHaveBeenCalled();
});
+ it("bills a hosted session MCP credits can't cover on the team's credits", async () => {
+ mocks.checkCredits
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 1000 });
+
+ expect((await create(true)).statusCode).toBe(200);
+ expect(mocks.checkCredits).toHaveBeenLastCalledWith(
+ expect.objectContaining({ featureId: "CREDITS" }),
+ );
+ expect(mocks.markHostedMcp).not.toHaveBeenCalled();
+ });
+
it("leaves a session not from the hosted MCP as it was", async () => {
mocks.checkCredits.mockResolvedValue({ allowed: false, remaining: 5 });
expect((await create(false)).statusCode).toBe(402);
@@ -243,6 +259,28 @@ describe("browser sessions from hosted MCP calls", () => {
expect(mocks.markHostedMcp).not.toHaveBeenCalled();
});
+ it("bills the session on team credits when a hosted prompt falls back to them", async () => {
+ mocks.checkCredits
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 1000 });
+
+ await reserveBrowserPromptCredits(makeReq(true) as any, session);
+ expect(mocks.markHostedMcp).not.toHaveBeenCalled();
+ expect(mocks.clearHostedMcp).toHaveBeenCalledWith("session-1");
+ });
+
+ it("refuses a team-credit prompt whose session can't be moved off MCP credits", async () => {
+ mocks.checkCredits
+ .mockResolvedValueOnce({ allowed: false, remaining: 0 })
+ .mockResolvedValueOnce({ allowed: true, remaining: 1000 });
+ mocks.clearHostedMcp.mockRejectedValue(new Error("redis down"));
+
+ await expect(
+ reserveBrowserPromptCredits(makeReq(true) as any, session),
+ ).rejects.toThrow("redis down");
+ expect(mocks.markUsedPrompt).not.toHaveBeenCalled();
+ });
+
it.each([
[true, { hostedMcp: true }],
[false, {}],
diff --git a/apps/api/src/controllers/v2/agent-credit-gate.ts b/apps/api/src/controllers/v2/agent-credit-gate.ts
index e3e4086d4..e379cacf3 100644
--- a/apps/api/src/controllers/v2/agent-credit-gate.ts
+++ b/apps/api/src/controllers/v2/agent-credit-gate.ts
@@ -3,6 +3,7 @@ import {
CREDITS_FEATURE_ID,
} from "../../services/autumn/autumn.service";
import { logger } from "../../lib/logger";
+import { checkHostedMcpCredits } from "../../services/autumn/hosted-mcp-gate";
export const AGENT_DEFAULT_MAX_CREDITS = 2500;
const AGENT_MIN_CREDITS = 20;
@@ -15,6 +16,8 @@ export type AgentCreditGate =
allowed: true;
maxCredits: number | undefined;
stopOnInsufficientCredits: boolean;
+ /** A hosted MCP run MCP credits can't cover, billed on the team's credits. */
+ onTeamCredits?: true;
};
/**
@@ -31,10 +34,12 @@ export type AgentCreditGate =
* - otherwise: `maxCredits` is capped at the balance, and the agent service
* is told to stop the run if the balance runs out mid-flight.
*
- * A hosted MCP run is gated on MCP credits, which its charges are tracked on.
+ * A hosted MCP run is gated on MCP credits, which its charges are tracked on,
+ * or on the team's own credits when MCP credits can't cover it.
*
* Fails open: whenever Autumn or firebill can't answer, the run starts as
- * requested.
+ * requested, except a hosted run MCP credits refuse, which stays refused when
+ * the team check can't answer.
*/
export async function gateAgentCredits({
teamId,
@@ -56,38 +61,47 @@ export async function gateAgentCredits({
};
if (!orgId || teamId === CREDIT_CHECK_EXEMPT_TEAM_ID) return asRequested;
- const feature = hostedMcp
- ? {
- featureId: await autumnService.hostedMcpFeatureId(
- teamId,
- CREDITS_FEATURE_ID,
- ),
- }
+ const params = (value: number, source: string) => ({
+ teamId,
+ orgId,
+ value,
+ properties: { source, path: "/agent", apiKeyId },
+ });
+ const hosted = hostedMcp
+ ? await checkHostedMcpCredits({
+ ...params(AGENT_MIN_CREDITS, "agentCreditGate"),
+ featureId: CREDITS_FEATURE_ID,
+ })
+ : null;
+ const feature = hosted ? { featureId: hosted.featureId } : {};
+ const onTeamCredits = hosted?.onTeamCredits
+ ? { onTeamCredits: true as const }
: {};
+ const runs: AgentCreditGate = { ...asRequested, ...onTeamCredits };
const check = (value: number, source: string) =>
- autumnService.checkCredits({
- teamId,
- orgId,
- value,
- properties: { source, path: "/agent", apiKeyId },
- ...feature,
- });
+ autumnService.checkCredits({ ...params(value, source), ...feature });
- const minimum = await check(AGENT_MIN_CREDITS, "agentCreditGate");
- if (minimum === null) return asRequested;
- if (!minimum.allowed) return { allowed: false, balance: minimum.remaining };
+ const minimum = hosted
+ ? hosted.result
+ : await check(AGENT_MIN_CREDITS, "agentCreditGate");
+ if (minimum === null) return runs;
+ if (!minimum.allowed)
+ return {
+ allowed: false,
+ balance: (hosted?.teamRefusal ?? minimum).remaining,
+ };
// An unlimited balance comes back as int64 max. Probing past it overflows
// the billing service's integer, so treat it as unlimited and skip the probe.
- if (minimum.remaining >= Number.MAX_SAFE_INTEGER) return asRequested;
+ if (minimum.remaining >= Number.MAX_SAFE_INTEGER) return runs;
const balance = Math.floor(minimum.remaining);
- if (!Number.isFinite(balance)) return asRequested;
+ if (!Number.isFinite(balance)) return runs;
const pastBalance = await check(
Math.max(balance, 0) + AGENT_MIN_CREDITS,
"agentCreditGate:overage",
);
- if (pastBalance === null || pastBalance.allowed) return asRequested;
- if (await autumnService.hasAutoTopUp(orgId)) return asRequested;
+ if (pastBalance === null || pastBalance.allowed) return runs;
+ if (await autumnService.hasAutoTopUp(orgId)) return runs;
if (balance <= 0) return { allowed: false, balance };
const requested = requestedMaxCredits ?? AGENT_DEFAULT_MAX_CREDITS;
@@ -99,5 +113,10 @@ export async function gateAgentCredits({
maxCredits,
});
}
- return { allowed: true, maxCredits, stopOnInsufficientCredits: true };
+ return {
+ allowed: true,
+ maxCredits,
+ stopOnInsufficientCredits: true,
+ ...onTeamCredits,
+ };
}
diff --git a/apps/api/src/controllers/v2/agent.ts b/apps/api/src/controllers/v2/agent.ts
index c28f0924d..1672bcbf1 100644
--- a/apps/api/src/controllers/v2/agent.ts
+++ b/apps/api/src/controllers/v2/agent.ts
@@ -272,6 +272,7 @@ export async function agentController(
}
maxCredits = gate.maxCredits;
stopOnInsufficientCredits = gate.stopOnInsufficientCredits;
+ if (gate.onTeamCredits) req.auth.hostedMcp = false;
}
await logRequest({
diff --git a/apps/api/src/lib/browser-lifecycle.ts b/apps/api/src/lib/browser-lifecycle.ts
index ccefef1c4..18daa61c5 100644
--- a/apps/api/src/lib/browser-lifecycle.ts
+++ b/apps/api/src/lib/browser-lifecycle.ts
@@ -21,6 +21,7 @@ import {
didBrowserSessionUsePrompt,
didBrowserSessionComeFromHostedMcp,
markBrowserSessionHostedMcp,
+ clearBrowserSessionHostedMcp,
listUnsettledHangarSessions,
BrowserSessionRow,
} from "./browser-sessions";
@@ -39,6 +40,8 @@ import {
DEFAULT_TEAM_LIMITS,
} from "../services/autumn/autumn.service";
import { billTeam } from "../services/billing/credit_billing";
+import { checkHostedMcpCredits } from "../services/autumn/hosted-mcp-gate";
+import type { TrackCreditsParams } from "../services/autumn/types";
import { orgIdForTeam } from "./team-org";
import { logRequest } from "../services/logging/log_job";
import { externalRequestId } from "./external-request-id";
@@ -65,6 +68,27 @@ export class BrowserSessionError extends Error {
}
}
+/**
+ * A browser charge's credit check. A hosted MCP call that MCP credits can't
+ * cover is billed on the team's own credits from here on, like an API-key call.
+ */
+async function checkBrowserCredits(
+ req: RequestWithAuth<any, any, any>,
+ params: TrackCreditsParams,
+) {
+ if (!req.auth.hostedMcp)
+ return {
+ result: await autumnService.checkCredits(params),
+ onTeamCredits: false,
+ };
+ const gate = await checkHostedMcpCredits({
+ ...params,
+ featureId: CREDITS_FEATURE_ID,
+ });
+ if (gate.onTeamCredits) req.auth.hostedMcp = false;
+ return gate;
+}
+
/** Returns the effective session policy and rejects disallowed ZDR requests. */
export function getBrowserZDR(
req: RequestWithAuth<any, any, any>,
@@ -176,7 +200,7 @@ async function createBrowserSessionInternal(
? Math.max(teamLimit, HOBBY_CONCURRENCY_LIMIT)
: teamLimit;
if (shouldBill && req.acuc?.org_id) {
- const credit = await autumnService.checkCredits({
+ const { result: credit } = await checkBrowserCredits(req, {
teamId: req.auth.team_id,
orgId: req.acuc.org_id,
value: estimatedCredits,
@@ -185,14 +209,6 @@ async function createBrowserSessionInternal(
path: req.path,
apiKeyId: req.acuc?.api_key_id ?? null,
},
- ...(req.auth.hostedMcp
- ? {
- featureId: await autumnService.hostedMcpFeatureId(
- req.auth.team_id,
- CREDITS_FEATURE_ID,
- ),
- }
- : {}),
});
if (credit !== null && !credit.allowed)
throw new BrowserSessionError(
@@ -432,8 +448,9 @@ export async function reserveBrowserPromptCredits(
session.ttl_total * 1000,
browserCreditsPerHour(true, session.zero_data_retention),
);
+ let onTeamCredits = false;
if (session.should_bill && req.acuc?.org_id) {
- const credit = await autumnService.checkCredits({
+ const gate = await checkBrowserCredits(req, {
teamId: session.team_id,
orgId: req.acuc.org_id,
value: credits,
@@ -442,20 +459,13 @@ export async function reserveBrowserPromptCredits(
path: req.path,
apiKeyId: req.acuc?.api_key_id ?? null,
},
- ...(req.auth.hostedMcp
- ? {
- featureId: await autumnService.hostedMcpFeatureId(
- req.auth.team_id,
- CREDITS_FEATURE_ID,
- ),
- }
- : {}),
});
- if (credit !== null && !credit.allowed)
+ if (gate.result !== null && !gate.result.allowed)
throw new BrowserSessionError(
402,
"Insufficient credits for a browser prompt session.",
);
+ onTeamCredits = gate.onTeamCredits;
}
// The same row lock guards settlement: a prompt admitted before stop
// records its rate before billing reads it, and a later prompt cannot
@@ -469,6 +479,10 @@ export async function reserveBrowserPromptCredits(
!(await updateKeylessBrowserCredits(current.team_id, current.id, credits))
)
throw new BrowserSessionError(429, KEYLESS_FREE_TIER_LIMIT_MESSAGE);
+ // A hosted prompt on team credits bills the whole session there, and must
+ // not run if the session would still settle on the MCP credits that refused.
+ if (current.should_bill && onTeamCredits)
+ await clearBrowserSessionHostedMcp(current.id);
await markBrowserSessionUsedPrompt(current.id);
// The prompt rate is most of a session's charge, so a hosted MCP prompt
// bills the session as hosted even when another call created it.
diff --git a/apps/api/src/lib/browser-sessions.ts b/apps/api/src/lib/browser-sessions.ts
index 0b0be4cf7..2393e0bcb 100644
--- a/apps/api/src/lib/browser-sessions.ts
+++ b/apps/api/src/lib/browser-sessions.ts
@@ -1,7 +1,7 @@
import { z } from "zod";
import { createHash } from "node:crypto";
import { and, asc, desc, eq, gt, like, lte, ne, sql } from "drizzle-orm";
-import { getValue, setValue } from "../services/redis";
+import { deleteKey, getValue, setValue } from "../services/redis";
import { redisRateLimitClient } from "../services/rate-limiter";
import { db } from "../db/connection";
import * as schema from "../db/schema";
@@ -368,6 +368,12 @@ export async function markBrowserSessionHostedMcp(
await setValue(hostedMcpFlagKey(sessionId), "1", PROFILE_DELETED_TTL_SECONDS);
}
+export async function clearBrowserSessionHostedMcp(
+ sessionId: string,
+): Promise<void> {
+ await deleteKey(hostedMcpFlagKey(sessionId));
+}
+
/** A flag lost to Redis bills the session as before: on regular credits. */
export async function didBrowserSessionComeFromHostedMcp(
sessionId: string,
diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.ts
index be87e95b2..5f33b7295 100644
--- a/apps/api/src/routes/shared.ts
+++ b/apps/api/src/routes/shared.ts
@@ -30,6 +30,7 @@ import {
CREDITS_FEATURE_ID,
} from "../services/autumn/autumn.service";
import { getTeamBalance } from "../services/autumn/usage";
+import { checkHostedMcpCredits } from "../services/autumn/hosted-mcp-gate";
import { getApiKeySpendLimit } from "../lib/api-key-spend-limit";
import {
ThirdPartyDataTermsRequiredError,
@@ -160,11 +161,6 @@ export function checkCreditsMiddleware(
}
const requestedCredits = minimum ?? 1;
- // Gated on the balance its charge will be tracked on.
- const gateFeatureId =
- mcpCredits && req.auth.hostedMcp
- ? await autumnService.hostedMcpFeatureId(req.auth.team_id, featureId)
- : featureId;
// No org means no billable identity to gate: keyless and preview teams
// carry none, and neither does the DB-authentication bypass. `checkCredits`
@@ -176,7 +172,7 @@ export function checkCreditsMiddleware(
return next();
}
- const autumnResult = await autumnService.checkCredits({
+ const check = {
teamId: req.auth.team_id,
// The ACUC already carries the org, so the credit check does not have
// to read `teams.org_id` for it.
@@ -187,8 +183,20 @@ export function checkCreditsMiddleware(
path: req.path,
apiKeyId: req.acuc?.api_key_id ?? null,
},
- featureId: gateFeatureId,
- });
+ featureId,
+ };
+ // Gated on the balance its charge will be tracked on.
+ const gate: Awaited<ReturnType<typeof checkHostedMcpCredits>> =
+ mcpCredits && req.auth.hostedMcp
+ ? await checkHostedMcpCredits(check)
+ : {
+ result: await autumnService.checkCredits(check),
+ featureId,
+ onTeamCredits: false,
+ };
+ if (gate.onTeamCredits) req.auth.hostedMcp = false;
+ const autumnResult = gate.result;
+ const gateFeatureId = gate.featureId;
// Autumn is the source of truth for credits. If it's unavailable
// (returns null), fail open β€” matches the behavior in browser.ts /
@@ -200,45 +208,66 @@ export function checkCreditsMiddleware(
}
const success = autumnResult.allowed;
+ const onGateFeature = {
+ remaining: autumnResult.remaining,
+ featureId: gateFeatureId,
+ onTeam: false,
+ };
+ // A hosted call both balances refuse tries the team clamp first when the
+ // team covers more, then MCP credits.
+ const clamps =
+ gate.teamRefusal && gate.teamRefusal.remaining > autumnResult.remaining
+ ? [
+ {
+ remaining: gate.teamRefusal.remaining,
+ featureId,
+ onTeam: true,
+ },
+ onGateFeature,
+ ]
+ : [onGateFeature];
// When Autumn allows the request (including overage), don't let a
// small remaining balance clamp downstream limits (e.g. crawl).
- const remainingCredits = success ? Infinity : autumnResult.remaining;
+ const remainingCredits = success ? Infinity : clamps[0].remaining;
req.account = { remainingCredits };
if (!success) {
const requestedLimit = Number((req.body as any)?.limit);
- const clampedLimit = Math.min(requestedLimit, remainingCredits);
- if (
- !_minimum &&
- req.body &&
- (req.body as any).limit !== undefined &&
- Number.isFinite(clampedLimit) &&
- clampedLimit > 0
- ) {
- // `remaining` is the team's credit balance, and a per-API-key spend
- // limit never lowers it, so a key over its own cap still reports a
- // healthy balance here. Re-check the clamped limit so only a genuinely
- // low team balance gets shrunk to fit; a per-key denial falls through
- // to the 402 below. A null re-check keeps the fail-open behavior.
- const clampedResult = await autumnService.checkCredits({
- teamId: req.auth.team_id,
- orgId,
- value: clampedLimit,
- properties: {
- source: "checkCreditsMiddleware:clamp",
- path: req.path,
- apiKeyId: req.acuc?.api_key_id ?? null,
- },
- featureId: gateFeatureId,
- });
-
- if (clampedResult === null || clampedResult.allowed) {
- logger.warn("Adjusting limit to remaining credits", {
+ for (const clampOn of clamps) {
+ const clampedLimit = Math.min(requestedLimit, clampOn.remaining);
+ if (
+ !_minimum &&
+ req.body &&
+ (req.body as any).limit !== undefined &&
+ Number.isFinite(clampedLimit) &&
+ clampedLimit > 0
+ ) {
+ // `remaining` is the team's credit balance, and a per-API-key spend
+ // limit never lowers it, so a key over its own cap still reports a
+ // healthy balance here. Re-check the clamped limit so only a genuinely
+ // low team balance gets shrunk to fit; a per-key denial falls through
+ // to the 402 below. A null re-check keeps the fail-open behavior.
+ const clampedResult = await autumnService.checkCredits({
teamId: req.auth.team_id,
- remainingCredits,
- clampedLimit,
+ orgId,
+ value: clampedLimit,
+ properties: {
+ source: "checkCreditsMiddleware:clamp",
+ path: req.path,
+ apiKeyId: req.acuc?.api_key_id ?? null,
+ },
+ featureId: clampOn.featureId,
});
- (req.body as any).limit = clampedLimit;
- return next();
+
+ if (clampedResult === null || clampedResult.allowed) {
+ if (clampOn.onTeam) req.auth.hostedMcp = false;
+ logger.warn("Adjusting limit to remaining credits", {
+ teamId: req.auth.team_id,
+ remainingCredits: clampOn.remaining,
+ clampedLimit,
+ });
+ (req.body as any).limit = clampedLimit;
+ return next();
+ }
}
}
@@ -291,7 +320,7 @@ export function checkCreditsMiddleware(
code: "mcp_credits_exhausted",
requested_credits: requestedCredits,
...(resetsAt ? { resets_at: resetsAt } : {}),
- error: `Insufficient credits for this connected-app request. Hosted MCP calls (from apps such as ChatGPT, Claude or Codex) spend a daily MCP credit allowance before your plan credits, and together they can't cover this request${resetsAt ? `; it resets at ${resetsAt}` : ""}. To continue now, use the Firecrawl MCP server with an API key, which bills your team's credits directly, or upgrade your plan at https://firecrawl.dev/pricing.`,
+ error: `Insufficient credits for this connected-app request. Hosted MCP calls (from apps such as ChatGPT, Claude or Codex) spend a daily MCP credit allowance first and then your team's credits, and neither can cover this request${resetsAt ? `; the allowance resets at ${resetsAt}` : ""}. To continue now, add credits or upgrade your plan at https://firecrawl.dev/pricing.`,
});
}
diff --git a/apps/api/src/services/alexandria/README.md b/apps/api/src/services/alexandria/README.md
index 40b685cad..dc7016e94 100644
--- a/apps/api/src/services/alexandria/README.md
+++ b/apps/api/src/services/alexandria/README.md
@@ -48,7 +48,8 @@ cannot be known (no org, preview team, Autumn error): this read fails closed
where the rate limiter fails open (Benzinga Schedule C.4: full text, WIIM,
analyst ratings), quote
(`/v1/retrieve/quote`), reserve with Autumn (`lockCredits`, lock
-`alexandria_<chargeId>`), execute `/v1/retrieve` with the budget and deadline
+`alexandria_<chargeId>`, or `alexandria_<chargeId>_team` for a hosted MCP hold
+that MCP credits refuse and team credits cover), execute `/v1/retrieve` with the budget and deadline
headers, settle the receipt (`finalizeCreditsLock`), enqueue the ledger write
on the billing queue with job id `alexandria-bill-<chargeId>`, and report to
`/v1/usage-events/billing`. Paid requests fail closed when authorization,
diff --git a/apps/api/src/services/alexandria/retrieve.test.ts b/apps/api/src/services/alexandria/retrieve.test.ts
index 140729b2e..3411e670f 100644
--- a/apps/api/src/services/alexandria/retrieve.test.ts
+++ b/apps/api/src/services/alexandria/retrieve.test.ts
@@ -176,6 +176,42 @@ it("holds and settles a hosted MCP call's whole budget on MCP credits", async ()
);
});
+it("holds a hosted MCP call MCP credits refuse on the team's own credits", async () => {
+ mocks.lock
+ .mockResolvedValueOnce({ status: "denied" })
+ .mockResolvedValueOnce({ status: "locked", lockId: "held" });
+ mocks.billAdd.mockRejectedValue(new Error("queue down"));
+
+ expect((await run({ hostedMcp: true })).status).toBe(200);
+ expect(mocks.lock.mock.calls.map(([hold]) => hold.featureId)).toEqual([
+ "MCP_CREDITS",
+ "credits",
+ ]);
+ expect(mocks.finalize).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ featureId: "credits" }),
+ );
+ expect(mocks.billAdd).toHaveBeenCalledWith(
+ "bill_team",
+ expect.objectContaining({
+ billing: expect.not.objectContaining({ hostedMcp: true }),
+ }),
+ expect.anything(),
+ );
+ expect(mocks.refund).toHaveBeenCalledExactlyOnceWith(
+ expect.objectContaining({ value: 3, featureId: "credits" }),
+ );
+});
+
+it("reports billing unavailable when the team-credit fallback hold can't be placed", async () => {
+ mocks.lock
+ .mockResolvedValueOnce({ status: "denied", reason: "out_of_credits" })
+ .mockResolvedValueOnce({ status: "denied", reason: "gate_unavailable" });
+
+ const refused = await run({ hostedMcp: true });
+ expect(refused).toMatchObject({ status: 503, executed: false });
+ expect(executions()).toHaveLength(0);
+});
+
it("refuses a different payload under the same x-request-id", async () => {
await run();
const other = await run({
diff --git a/apps/api/src/services/alexandria/retrieve.ts b/apps/api/src/services/alexandria/retrieve.ts
index 9949b6803..f4cbbee02 100644
--- a/apps/api/src/services/alexandria/retrieve.ts
+++ b/apps/api/src/services/alexandria/retrieve.ts
@@ -258,12 +258,11 @@ export async function retrieveProviders(input: {
return notExecuted(unresolved(id));
}
- const featureId = input.hostedMcp
- ? await autumnService.hostedMcpFeatureId(
- input.teamId,
- featureIdForBillingEndpoint("scrape"),
- )
- : featureIdForBillingEndpoint("scrape");
+ const teamFeatureId = featureIdForBillingEndpoint("scrape");
+ let featureId = input.hostedMcp
+ ? await autumnService.hostedMcpFeatureId(input.teamId, teamFeatureId)
+ : teamFeatureId;
+ let hostedMcp = input.hostedMcp === true;
const properties = {
source: "alexandria",
endpoint: "scrape",
@@ -391,15 +390,31 @@ export async function retrieveProviders(input: {
input.teamId,
input.orgId,
));
- hold = await autumnService.lockCredits({
- teamId: input.teamId,
- orgId: input.orgId,
- value: maximumCredits,
- lockId: `alexandria_${id}`,
- expiresAt: record.deadline + HOLD_GRACE_MS,
- featureId,
- properties,
- });
+ const orgId = input.orgId;
+ const lock = (feature: string, lockId: string) =>
+ autumnService.lockCredits({
+ teamId: input.teamId,
+ orgId,
+ value: maximumCredits,
+ lockId,
+ expiresAt: record.deadline + HOLD_GRACE_MS,
+ featureId: feature,
+ properties,
+ });
+ hold = await lock(featureId, `alexandria_${id}`);
+ // MCP credits can't reach team-scoped grants such as coupons, so a
+ // hosted MCP hold they refuse is tried on the team's own credits.
+ if (
+ hold.status === "denied" &&
+ (!hold.reason || hold.reason === "out_of_credits") &&
+ featureId !== teamFeatureId
+ ) {
+ hold = await lock(teamFeatureId, `alexandria_${id}_team`);
+ if (hold.status === "locked") {
+ featureId = teamFeatureId;
+ hostedMcp = false;
+ }
+ }
}
if (hold.status === "denied")
return refuse(
@@ -514,7 +529,7 @@ export async function retrieveProviders(input: {
input.apiKeyId,
credits,
refundable,
- input.hostedMcp === true,
+ hostedMcp,
)
: settled;
const charged =
diff --git a/apps/api/src/services/autumn/hosted-mcp-gate.ts b/apps/api/src/services/autumn/hosted-mcp-gate.ts
new file mode 100644
index 000000000..f04aef50d
--- /dev/null
+++ b/apps/api/src/services/autumn/hosted-mcp-gate.ts
@@ -0,0 +1,43 @@
+import { autumnService } from "./autumn.service";
+import type { TrackCreditsParams } from "./types";
+
+type CheckResult = Awaited<ReturnType<typeof autumnService.checkCredits>>;
+
+/**
+ * Checks a hosted MCP charge on MCP credits, the balance it is billed to, and
+ * when they refuse it, on the team's own `featureId` balance, where team-scoped
+ * grants such as coupons live out of reach of the MCP credits check.
+ * `onTeamCredits` means the charge must then be billed like an API-key call.
+ * A team check that can't answer leaves the MCP refusal standing; one that
+ * refuses too comes back as `teamRefusal`.
+ */
+export async function checkHostedMcpCredits(
+ params: TrackCreditsParams & { featureId: string },
+): Promise<{
+ result: CheckResult;
+ featureId: string;
+ onTeamCredits: boolean;
+ teamRefusal?: NonNullable<CheckResult>;
+}> {
+ const mcpFeatureId = await autumnService.hostedMcpFeatureId(
+ params.teamId,
+ params.featureId,
+ );
+ const onMcp = await autumnService.checkCredits({
+ ...params,
+ featureId: mcpFeatureId,
+ });
+ const onMcpCredits = {
+ result: onMcp,
+ featureId: mcpFeatureId,
+ onTeamCredits: false,
+ };
+ if (mcpFeatureId === params.featureId || onMcp === null || onMcp.allowed)
+ return onMcpCredits;
+
+ const onTeam = await autumnService.checkCredits(params);
+ if (onTeam === null) return onMcpCredits;
+ return onTeam.allowed
+ ? { result: onTeam, featureId: params.featureId, onTeamCredits: true }
+ : { ...onMcpCredits, teamRefusal: onTeam };
+}