Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. π₯
TypeScript aiai-agentsai-crawlerai-scrapingai-searchcrawlerdata-extractionhtml-to-markdownllmmarkdownscraperscrapingweb-crawlerweb-dataweb-data-extractionweb-scraperweb-scrapingweb-searchwebscraping
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mdindex 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 closedwhere 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 deadlineheaders, settle the receipt (`finalizeCreditsLock`), enqueue the ledger writeon 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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 };+}