Skip to content

Supercharge your AI agents with data from the web and beyond. Building the library for superintelligence. 🔥

feat(api): raise rate limits for hosted MCP calls on v2 endpoints (#5441)

Max67a98c3785b0
diff --git a/apps/api/src/__tests__/routes/hosted-mcp-rate-limit.routes.test.ts b/apps/api/src/__tests__/routes/hosted-mcp-rate-limit.routes.test.ts
new file mode 100644
index 000000000..0fe10e61f
--- /dev/null
+++ b/apps/api/src/__tests__/routes/hosted-mcp-rate-limit.routes.test.ts
@@ -0,0 +1,57 @@
+import express from "express";
+import request from "supertest";
+
+// Real routers; auth is stubbed to answer with the options its route passed,
+// so each request shows whether the route opts in to the hosted MCP minimums.
+vi.mock("../../routes/shared", async importOriginal => {
+ const actual = await importOriginal<typeof import("../../routes/shared")>();
+ return {
+ ...actual,
+ authMiddleware:
+ (_mode: unknown, options: { hostedMcpRateLimit?: boolean } = {}) =>
+ (_req: any, res: any) =>
+ res
+ .status(200)
+ .json({ hostedMcpRateLimit: options.hostedMcpRateLimit === true }),
+ };
+});
+
+import { v1Router } from "../../routes/v1";
+import { v2Router } from "../../routes/v2";
+
+const app = express();
+app.use(express.json());
+app.use("/v1", v1Router);
+app.use("/v2", v2Router);
+
+async function optsIn(path: string): Promise<boolean> {
+ const res = await request(app).post(path).send({});
+ expect(res.status).toBe(200);
+ return res.body.hostedMcpRateLimit;
+}
+
+describe("hosted MCP rate-limit opt-in", () => {
+ it.each([
+ "/v2/scrape",
+ "/v2/search",
+ "/v2/batch/scrape",
+ "/v2/parse",
+ "/v2/parse/upload-url",
+ "/v2/map",
+ "/v2/crawl",
+ "/v2/extract",
+ "/v2/agent",
+ ])("is set on %s", async path => {
+ expect(await optsIn(path)).toBe(true);
+ });
+
+ it.each([
+ "/v1/scrape",
+ "/v1/search",
+ "/v1/batch/scrape",
+ "/v1/map",
+ "/v1/crawl",
+ ])("is not set on %s", async path => {
+ expect(await optsIn(path)).toBe(false);
+ });
+});
diff --git a/apps/api/src/controllers/__tests__/auth.test.ts b/apps/api/src/controllers/__tests__/auth.test.ts
index 7983ff7e6..5143edb6d 100644
--- a/apps/api/src/controllers/__tests__/auth.test.ts
+++ b/apps/api/src/controllers/__tests__/auth.test.ts
@@ -11,6 +11,7 @@ import { redlock } from "../../services/redlock";
import { deleteKey, getValue, setValue } from "../../services/redis";
import {
getAutumnRateLimiter,
+ getHostedMcpRateLimiter,
getRateLimiter,
HOBBY_RATE_LIMIT_MULTIPLIER,
} from "../../services/rate-limiter";
@@ -76,6 +77,7 @@ vi.mock("../../services/rate-limiter", async importOriginal => {
return {
...actual,
getRateLimiter: vi.fn(),
+ getHostedMcpRateLimiter: vi.fn(),
getAutumnRateLimiter: vi.fn(),
};
});
@@ -1188,6 +1190,419 @@ describe("authenticateUser", () => {
});
});
+ describe("hosted MCP rate-limit minimum", () => {
+ const API_KEY = "Bearer 00000000-0000-4000-8000-000000000000";
+ const requestWith = (
+ authorization: string,
+ extra: {
+ body?: Record<string, unknown>;
+ headers?: Record<string, string>;
+ } = {},
+ ) => ({
+ headers: { authorization, ...extra.headers },
+ socket: { remoteAddress: "127.0.0.1" },
+ body: extra.body,
+ });
+ // Options of a route that opts in to the hosted MCP minimum.
+ const HOSTED_MCP_ROUTE = { hostedMcpRateLimit: true };
+ const planConsume = vi.fn().mockResolvedValue(undefined);
+ const hostedMcpConsume = vi.fn().mockResolvedValue(undefined);
+
+ beforeEach(() => {
+ config.USE_DB_AUTHENTICATION = true;
+ config.MCP_DELEGATED_CREDENTIAL_SECRET = "mcp-delegation-secret";
+ config.KEYLESS_PROXY_SECRET = "hosted-mcp-proxy-secret";
+ vi.mocked(getValue).mockResolvedValue(null);
+ vi.mocked(authCreditUsageChunk).mockResolvedValue([
+ {
+ api_key: "00000000-0000-4000-8000-000000000000",
+ api_key_id: 1,
+ team_id: "team-1",
+ org_id: "org-1",
+ flags: {},
+ },
+ ]);
+ vi.mocked(redlock.using).mockImplementation(
+ async (_keys, _ttl, _options, fn) => fn({ aborted: false } as never),
+ );
+ vi.mocked(getAutumnRateLimiter).mockReturnValue({
+ consume: planConsume,
+ } as never);
+ vi.mocked(getHostedMcpRateLimiter).mockReturnValue({
+ consume: hostedMcpConsume,
+ } as never);
+ });
+
+ it.each([RateLimiterMode.Scrape, RateLimiterMode.Search])(
+ "uses only the raised limiter for a verified hosted MCP credential (%s)",
+ async mode => {
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ mode,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(getHostedMcpRateLimiter).toHaveBeenCalledExactlyOnceWith(
+ mode,
+ 1,
+ {},
+ );
+ expect(hostedMcpConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(planConsume).not.toHaveBeenCalled();
+ },
+ );
+
+ it("uses the raised limiter for other multiplier-scaled modes", async () => {
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Map,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(getHostedMcpRateLimiter).toHaveBeenCalledExactlyOnceWith(
+ RateLimiterMode.Map,
+ 1,
+ {},
+ );
+ expect(hostedMcpConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(planConsume).not.toHaveBeenCalled();
+ });
+
+ it("uses only the raised limiter for an API key the hosted MCP relayed", async () => {
+ const auth = await authenticateUser(
+ requestWith(API_KEY, {
+ headers: { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },
+ }),
+ {},
+ RateLimiterMode.Search,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(getHostedMcpRateLimiter).toHaveBeenCalledExactlyOnceWith(
+ RateLimiterMode.Search,
+ 1,
+ {},
+ );
+ expect(hostedMcpConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(planConsume).not.toHaveBeenCalled();
+ });
+
+ it.each([
+ ["a verified delegated credential", `Bearer ${signDelegation()}`, {}],
+ [
+ "an API key with the proxy secret",
+ API_KEY,
+ { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },
+ ],
+ ])(
+ "keeps the plan limit on a route that does not opt in, for %s",
+ async (_label, authorization, headers) => {
+ // Parse and batch scrape share the scrape mode but not the opt-in.
+ const auth = await authenticateUser(
+ requestWith(authorization, { headers }),
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(getHostedMcpRateLimiter).not.toHaveBeenCalled();
+ expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(hostedMcpConsume).not.toHaveBeenCalled();
+ },
+ );
+
+ it("keeps the plan limit when no proxy secret is configured", async () => {
+ config.KEYLESS_PROXY_SECRET = undefined;
+
+ await authenticateUser(
+ requestWith(API_KEY, {
+ headers: { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },
+ }),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(getHostedMcpRateLimiter).not.toHaveBeenCalled();
+ expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ });
+
+ it("does not enroll the org in the experiment through a hosted MCP call", async () => {
+ await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(getRateLimitExperimentVariant).not.toHaveBeenCalled();
+ expect(hostedMcpConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ });
+
+ it("runs the experiment when the hosted MCP minimum does not apply", async () => {
+ vi.mocked(getHostedMcpRateLimiter).mockReturnValue(undefined);
+
+ await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(getRateLimitExperimentVariant).toHaveBeenCalledOnce();
+ });
+
+ it.each([
+ ["", {}],
+ [
+ " with the proxy secret",
+ { "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret" },
+ ],
+ ])(
+ "keeps the plan limit for an OAuth access token sent straight to the API%s",
+ async (_label, headers) => {
+ 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 }),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(getHostedMcpRateLimiter).not.toHaveBeenCalled();
+ expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(hostedMcpConsume).not.toHaveBeenCalled();
+ },
+ );
+
+ it.each([
+ ["an MCP origin", { body: { origin: "mcp-ua-claude-user" } }],
+ ["an MCP X-Origin header", { headers: { "x-origin": "mcp" } }],
+ ["the CLI integration", { body: { origin: "api", integration: "cli" } }],
+ [
+ "a wrong proxy secret",
+ { headers: { "x-firecrawl-keyless-secret": "not-the-secret" } },
+ ],
+ ["no origin", {}],
+ ])("keeps the plan limit for an API key with %s", async (_label, extra) => {
+ const auth = await authenticateUser(
+ requestWith(API_KEY, extra),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(getHostedMcpRateLimiter).not.toHaveBeenCalled();
+ expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(hostedMcpConsume).not.toHaveBeenCalled();
+ });
+
+ it("does not raise the limit for a credential that fails verification", async () => {
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation({}, "wrong-secret")}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(false);
+ expect(getHostedMcpRateLimiter).not.toHaveBeenCalled();
+ expect(hostedMcpConsume).not.toHaveBeenCalled();
+ });
+
+ it("keeps the plan limiter when the minimum does not raise it", async () => {
+ vi.mocked(getHostedMcpRateLimiter).mockReturnValue(undefined);
+
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(auth.success).toBe(true);
+ expect(planConsume).toHaveBeenCalledExactlyOnceWith("team-1");
+ expect(hostedMcpConsume).not.toHaveBeenCalled();
+ });
+
+ describe("concurrency", () => {
+ const PROXY_SECRET = {
+ "x-firecrawl-keyless-secret": "hosted-mcp-proxy-secret",
+ };
+ const concurrencyOf = (
+ auth: Awaited<ReturnType<typeof authenticateUser>>,
+ ) => (auth.success ? auth.chunk?.concurrency_limit : undefined);
+ const limits = (
+ concurrency_limit: number,
+ rate_limit_multiplier: number,
+ ) =>
+ vi.mocked(autumnService.getTeamLimits).mockResolvedValue({
+ concurrency_limit,
+ rate_limit_multiplier,
+ is_paid_plan: rate_limit_multiplier > 1,
+ });
+
+ it("raises a free team to 25 for a verified hosted MCP credential", async () => {
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(25);
+ });
+
+ it("raises a hobby team to 50 for an API key the hosted MCP relayed", async () => {
+ limits(5, HOBBY_RATE_LIMIT_MULTIPLIER);
+
+ const auth = await authenticateUser(
+ requestWith(API_KEY, { headers: PROXY_SECRET }),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(50);
+ });
+
+ it("raises a standard team to 75 and asks for the standard rate tier", async () => {
+ limits(50, 50);
+
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(75);
+ expect(getHostedMcpRateLimiter).toHaveBeenCalledExactlyOnceWith(
+ RateLimiterMode.Scrape,
+ 50,
+ {},
+ );
+ });
+
+ it("keeps a free team on the free tier when trusted agent traffic floors its multiplier", async () => {
+ config.AGENT_INTEROP_SECRET = "agent-secret";
+
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`, {
+ body: {
+ __agentInterop: {
+ auth: "agent-secret",
+ requestId: "req-1",
+ shouldBill: true,
+ },
+ },
+ }),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(25);
+ expect(getHostedMcpRateLimiter).toHaveBeenCalledExactlyOnceWith(
+ RateLimiterMode.Scrape,
+ 1,
+ {},
+ );
+ });
+
+ it.each([
+ ["growth", 100, 500],
+ ["a team already above its tier", 30, 1],
+ ])(
+ "keeps the plan limit for %s",
+ async (_label, concurrency, multiplier) => {
+ limits(concurrency, multiplier);
+
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(concurrency);
+ },
+ );
+
+ it("keeps the plan limit on a route that does not opt in", async () => {
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ RateLimiterMode.Scrape,
+ );
+
+ expect(concurrencyOf(auth)).toBe(2);
+ });
+
+ it.each([RateLimiterMode.Search, RateLimiterMode.Crawl])(
+ "keeps the plan limit for %s, which does not check the semaphore",
+ async mode => {
+ const auth = await authenticateUser(
+ requestWith(`Bearer ${signDelegation()}`),
+ {},
+ mode,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(2);
+ },
+ );
+
+ it.each([
+ ["an MCP origin", { body: { origin: "mcp-ua-claude-user" } }],
+ [
+ "a wrong proxy secret",
+ { headers: { "x-firecrawl-keyless-secret": "not-the-secret" } },
+ ],
+ ["no origin", {}],
+ ])(
+ "keeps the plan limit for an API key with %s",
+ async (_label, extra) => {
+ const auth = await authenticateUser(
+ requestWith(API_KEY, extra),
+ {},
+ RateLimiterMode.Scrape,
+ HOSTED_MCP_ROUTE,
+ );
+
+ expect(concurrencyOf(auth)).toBe(2);
+ },
+ );
+ });
+ });
+
describe("agent interop rate-limit floor", () => {
const flags = {};
const agentRequest = (auth: string) => ({
diff --git a/apps/api/src/controllers/auth.ts b/apps/api/src/controllers/auth.ts
index 1d5b7de8e..ff0c3b1f8 100644
--- a/apps/api/src/controllers/auth.ts
+++ b/apps/api/src/controllers/auth.ts
@@ -9,6 +9,8 @@ import { getAgentSponsorStatus } from "../services/agent-sponsor";
import {
getRateLimiter,
getAutumnRateLimiter,
+ getHostedMcpConcurrencyLimit,
+ getHostedMcpRateLimiter,
getRateLimitOverride,
HOBBY_RATE_LIMIT_MULTIPLIER,
rateLimitExperimentApplies,
@@ -857,6 +859,10 @@ type AuthenticateOptions = {
// Route opt-in: a trusted agent-interop request may authenticate with a
// hosted_mcp_oauth key, which agent runs started from the hosted MCP carry.
allowAgentManagedKey?: boolean;
+ // Route opt-in: calls the hosted MCP makes get the raised per-minute and
+ // concurrency minimums (see getHostedMcpRateLimiter and
+ // getHostedMcpConcurrencyLimit) only on routes that set this.
+ hostedMcpRateLimit?: boolean;
};
async function supaAuthenticateUser(
@@ -902,6 +908,9 @@ async function supaAuthenticateUser(
let teamId: string | null = null;
let chunk: AuthCreditUsageChunk | null = null;
+ // Set only once a hosted MCP delegated credential has verified, so the
+ // client never decides it.
+ let hostedMcpDelegation = false;
if (token == "this_is_just_a_preview_token") {
throw new Error(
"Unauthenticated Playground calls are temporarily disabled due to abuse. Please sign up.",
@@ -947,6 +956,7 @@ async function supaAuthenticateUser(
teamId = chunk.team_id;
subscriptionData = { team_id: teamId };
+ hostedMcpDelegation = true;
rateLimiter = await buildAuthenticatedRateLimiter(
chunk,
mode,
@@ -1139,7 +1149,46 @@ async function supaAuthenticateUser(
mode,
minRateMultiplier,
);
- if (
+ // 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
+ // minimum. Two signals prove the hosted MCP made the call: a verified
+ // delegated credential (managed OAuth sessions) or the proxy secret it
+ // shares with the API (sessions that send a plain API key).
+ // `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.
+ const hostedMcpRaise =
+ options?.hostedMcpRateLimit === true &&
+ (hostedMcpDelegation ||
+ (!token.startsWith("fco_") &&
+ timingSafeSecretEqual(
+ req.headers["x-firecrawl-keyless-secret"],
+ config.KEYLESS_PROXY_SECRET,
+ )));
+ // The tiers follow the team's own plan multiplier, not `multiplier`,
+ // which trusted agent traffic floors at hobby, so a free team never gets
+ // the hobby tier.
+ const hostedMcpLimiter = hostedMcpRaise
+ ? getHostedMcpRateLimiter(mode, chunk.rate_limit_multiplier, chunk.flags)
+ : undefined;
+ const hostedMcpConcurrency = hostedMcpRaise
+ ? getHostedMcpConcurrencyLimit(
+ mode,
+ chunk.concurrency_limit,
+ chunk.rate_limit_multiplier,
+ chunk.flags,
+ )
+ : undefined;
+ if (hostedMcpConcurrency !== undefined) {
+ // Only this request's chunk changes; the cached team limits do not.
+ chunk = { ...chunk, concurrency_limit: hostedMcpConcurrency };
+ }
+ if (hostedMcpLimiter) {
+ // At or above the treatment minimum on every plan it applies to, so the
+ // experiment cannot change this call's limit and does not enroll the
+ // org through it.
+ rateLimiter = hostedMcpLimiter;
+ } else if (
rateLimitExperimentApplies(mode, multiplier, chunk.flags) &&
(await getRateLimitExperimentVariant({
orgId: chunk.org_id,
diff --git a/apps/api/src/routes/shared.ts b/apps/api/src/routes/shared.ts
index 4f138b19d..743053bcd 100644
--- a/apps/api/src/routes/shared.ts
+++ b/apps/api/src/routes/shared.ts
@@ -273,6 +273,7 @@ export function authMiddleware(
options: {
allowKeyless?: boolean | ((req: RequestWithMaybeAuth) => boolean);
allowAgentManagedKey?: boolean;
+ hostedMcpRateLimit?: boolean;
} = {},
): (req: RequestWithMaybeAuth, res: Response, next: NextFunction) => void {
return (req, res, next) => {
diff --git a/apps/api/src/routes/v2.ts b/apps/api/src/routes/v2.ts
index 5bbe43e89..5b0e2fca6 100644
--- a/apps/api/src/routes/v2.ts
+++ b/apps/api/src/routes/v2.ts
@@ -44,7 +44,7 @@ import { crawlStatusWSController } from "../controllers/v2/crawl-status-ws";
import { extractController } from "../controllers/v2/extract";
import { extractStatusController } from "../controllers/v2/extract-status";
import {
- authMiddleware,
+ authMiddleware as sharedAuthMiddleware,
checkCreditsMiddleware,
blocklistMiddleware,
scrapeBlocklistMiddleware,
@@ -124,6 +124,12 @@ import {
slackStatusController,
} from "../controllers/v2/slack";
import { agentListController } from "../controllers/v2/agent-list";
+
+// Every v2 route opts in to the hosted MCP minimums (see AuthenticateOptions
+// in controllers/auth.ts); /v1 routes do not.
+const authMiddleware: typeof sharedAuthMiddleware = (mode, options = {}) =>
+ sharedAuthMiddleware(mode, { ...options, hostedMcpRateLimit: true });
+
export const v2Router = express.Router();
expressWs(express()).applyTo(v2Router);
diff --git a/apps/api/src/services/rate-limiter.test.ts b/apps/api/src/services/rate-limiter.test.ts
index 55a5eb972..418d1735e 100644
--- a/apps/api/src/services/rate-limiter.test.ts
+++ b/apps/api/src/services/rate-limiter.test.ts
@@ -13,6 +13,8 @@ vi.mock("ioredis", () => ({
import {
getAutumnRateLimiter,
+ getHostedMcpConcurrencyLimit,
+ getHostedMcpRateLimiter,
rateLimitExperimentApplies,
} from "./rate-limiter";
@@ -489,6 +491,131 @@ describe("getAutumnRateLimiter", () => {
});
});
+ describe("hosted MCP minimum", () => {
+ it("raises free and hobby to 600 and standard to 2,000 in a bucket of its own", () => {
+ for (const mode of [RateLimiterMode.Scrape, RateLimiterMode.Search]) {
+ // Free, hobby and the ×11 and ×25 variants round down to hobby;
+ // standard and the ×60 to ×199 variants round down to standard.
+ for (const [multiplier, limit] of [
+ [1, 600],
+ [5, 600],
+ [10, 600],
+ [11, 600],
+ [25, 600],
+ [50, 2000],
+ [60, 2000],
+ [199, 2000],
+ ]) {
+ const limiter = getHostedMcpRateLimiter(mode, multiplier);
+ expect(limiter?.points).toBe(limit);
+ expect(limiter?.keyPrefix).toBe(`hostedMcp:${mode}`);
+ }
+ }
+ });
+
+ it("leaves plans already at or above their minimum on their normal limiter", () => {
+ // A ×200 variant (exactly 2,000), growth and scale.
+ for (const multiplier of [200, 500, 1000]) {
+ expect(
+ getHostedMcpRateLimiter(RateLimiterMode.Scrape, multiplier),
+ ).toBe(undefined);
+ }
+ });
+
+ it("scales every multiplier-scaled mode by the same tier multiplier", () => {
+ // ×60 on free and hobby, ×200 on standard, applied to each mode's base.
+ for (const [mode, free, standard] of [
+ [RateLimiterMode.Map, 600, 2000],
+ [RateLimiterMode.Exchange, 600, 2000],
+ [RateLimiterMode.BrowserExecute, 600, 2000],
+ [RateLimiterMode.Crawl, 120, 400],
+ [RateLimiterMode.Extract, 120, 400],
+ [RateLimiterMode.Browser, 120, 400],
+ [RateLimiterMode.CrawlStatus, 30000, 100000],
+ [RateLimiterMode.ExtractStatus, 30000, 100000],
+ ] as const) {
+ const freeLimiter = getHostedMcpRateLimiter(mode, 1);
+ expect(freeLimiter?.points).toBe(free);
+ expect(freeLimiter?.keyPrefix).toBe(`hostedMcp:${mode}`);
+ expect(getHostedMcpRateLimiter(mode, 10)?.points).toBe(free);
+ expect(getHostedMcpRateLimiter(mode, 50)?.points).toBe(standard);
+ expect(getHostedMcpRateLimiter(mode, 500)).toBe(undefined);
+ }
+ });
+
+ it("leaves flat modes and overridden modes alone", () => {
+ for (const mode of [
+ RateLimiterMode.ExchangeDiscover,
+ RateLimiterMode.Account,
+ RateLimiterMode.Research,
+ ]) {
+ expect(getHostedMcpRateLimiter(mode, 1)).toBe(undefined);
+ }
+ expect(
+ getHostedMcpRateLimiter(
+ RateLimiterMode.Scrape,
+ 1,
+ flagsWith({ [RateLimiterMode.Scrape]: 5 }),
+ ),
+ ).toBe(undefined);
+ });
+
+ it("treats a multiplier of zero or below as ×1", () => {
+ expect(getHostedMcpRateLimiter(RateLimiterMode.Scrape, 0)?.points).toBe(
+ 600,
+ );
+ });
+ });
+
+ describe("hosted MCP concurrency minimum", () => {
+ it("raises free to 25, hobby to 50 and standard to 75", () => {
+ for (const [multiplier, limit, concurrency] of [
+ [1, 2, 25],
+ [10, 5, 50],
+ [25, 5, 50],
+ [50, 50, 75],
+ [100, 50, 75],
+ ]) {
+ expect(
+ getHostedMcpConcurrencyLimit(
+ RateLimiterMode.Scrape,
+ limit,
+ multiplier,
+ ),
+ ).toBe(concurrency);
+ }
+ });
+
+ it("keeps a team limit already at or above its tier", () => {
+ expect(getHostedMcpConcurrencyLimit(RateLimiterMode.Scrape, 25, 1)).toBe(
+ undefined,
+ );
+ expect(getHostedMcpConcurrencyLimit(RateLimiterMode.Scrape, 60, 10)).toBe(
+ undefined,
+ );
+ expect(getHostedMcpConcurrencyLimit(RateLimiterMode.Scrape, 75, 50)).toBe(
+ undefined,
+ );
+ });
+
+ it("leaves growth and up, other modes and overridden modes alone", () => {
+ expect(
+ getHostedMcpConcurrencyLimit(RateLimiterMode.Scrape, 50, 500),
+ ).toBe(undefined);
+ for (const mode of [RateLimiterMode.Search, RateLimiterMode.Crawl]) {
+ expect(getHostedMcpConcurrencyLimit(mode, 2, 1)).toBe(undefined);
+ }
+ expect(
+ getHostedMcpConcurrencyLimit(
+ RateLimiterMode.Scrape,
+ 2,
+ 1,
+ flagsWith({ [RateLimiterMode.Scrape]: 5 }),
+ ),
+ ).toBe(undefined);
+ });
+ });
+
it("replaces the computed limit with the override for that mode", () => {
const limiter = getAutumnRateLimiter(
RateLimiterMode.Scrape,
diff --git a/apps/api/src/services/rate-limiter.ts b/apps/api/src/services/rate-limiter.ts
index a350b6285..70762952d 100644
--- a/apps/api/src/services/rate-limiter.ts
+++ b/apps/api/src/services/rate-limiter.ts
@@ -141,6 +141,105 @@ export function getAutumnRateLimiter(
return createRateLimiter(`${mode}`, rateLimit);
}
+/**
+ * Modes whose concurrency the hosted MCP tier raises. Scrape is the mode that
+ * checks the team semaphore at request time (`/v2/scrape` and `/v2/parse`),
+ * so the raised scrape rate is not cut back to the plan's concurrency; other
+ * modes keep the plan's concurrency.
+ */
+const HOSTED_MCP_CONCURRENCY_MODES: ReadonlySet<RateLimiterMode> = new Set([
+ RateLimiterMode.Scrape,
+]);
+
+/** Autumn rate-limit multipliers of the standard and growth plans. */
+const STANDARD_RATE_LIMIT_MULTIPLIER = 50;
+const GROWTH_RATE_LIMIT_MULTIPLIER = 500;
+
+type HostedMcpTier = { rateMultiplier: number; concurrency: number };
+
+/**
+ * Minimums for hosted MCP calls by plan. The rate multiplier applies to every
+ * multiplier-scaled mode in BASE_RATE_LIMITS, so each endpoint scales evenly:
+ * ×60 is 600/min on scrape and search on free and hobby, and ×200 is 2,000/min
+ * on standard. The concurrency minimum keeps the team semaphore from cutting
+ * the raised scrape rate back to the plan's concurrency.
+ */
+const HOSTED_MCP_FREE: HostedMcpTier = { rateMultiplier: 60, concurrency: 25 };
+const HOSTED_MCP_HOBBY: HostedMcpTier = { rateMultiplier: 60, concurrency: 50 };
+const HOSTED_MCP_STANDARD: HostedMcpTier = {
+ rateMultiplier: 200,
+ concurrency: 75,
+};
+
+/**
+ * The hosted MCP tier for a team's Autumn plan multiplier: free below hobby,
+ * hobby from hobby, standard from standard, so off-tier variants round down
+ * to the tier below them. Undefined from growth up and under an org override
+ * for the mode, which keep their own limits.
+ */
+function hostedMcpTier(
+ mode: RateLimiterMode,
+ multiplier: number,
+ flags?: TeamFlags,
+): HostedMcpTier | undefined {
+ if (getRateLimitOverride(mode, flags?.rateLimitOverrides) !== undefined) {
+ return undefined;
+ }
+ const safeMultiplier = multiplier > 0 ? multiplier : 1;
+ if (safeMultiplier >= GROWTH_RATE_LIMIT_MULTIPLIER) return undefined;
+ if (safeMultiplier >= STANDARD_RATE_LIMIT_MULTIPLIER) {
+ return HOSTED_MCP_STANDARD;
+ }
+ if (safeMultiplier >= HOBBY_RATE_LIMIT_MULTIPLIER) return HOSTED_MCP_HOBBY;
+ return HOSTED_MCP_FREE;
+}
+
+/**
+ * The limiter for a call the hosted MCP made (verified in controllers/auth.ts)
+ * at `base × tier multiplier` (see hostedMcpTier), or undefined for modes
+ * without a base (flat limits), when there is no tier, or when the team's own
+ * multiplier is already at least the tier's.
+ *
+ * Where the minimum applies, the call counts in its own bucket, so those hosted
+ * MCP calls do not use up the team's API budget for the mode and API calls do
+ * not use up the hosted MCP one. Where it does not apply, the call uses the
+ * team's normal limiter.
+ */
+export function getHostedMcpRateLimiter(
+ mode: RateLimiterMode,
+ multiplier: number = 1,
+ flags?: TeamFlags,
+): RateLimiterRedis | undefined {
+ const base = BASE_RATE_LIMITS[mode];
+ if (base === undefined) return undefined;
+ const tier = hostedMcpTier(mode, multiplier, flags);
+ if (!tier) return undefined;
+ const safeMultiplier = multiplier > 0 ? multiplier : 1;
+ if (safeMultiplier >= tier.rateMultiplier) return undefined;
+ return createRateLimiter(`hostedMcp:${mode}`, base * tier.rateMultiplier);
+}
+
+/**
+ * The concurrency limit for a hosted MCP scrape call at its plan tier (see
+ * hostedMcpTier), or undefined for other modes, when there is no tier, or
+ * when the team's own limit is already at least the tier's.
+ *
+ * This raises the ceiling the request checks against the team's shared
+ * concurrency pool; it is not a pool of its own, so the team cannot run its
+ * plan limit plus the tier's at once.
+ */
+export function getHostedMcpConcurrencyLimit(
+ mode: RateLimiterMode,
+ concurrencyLimit: number,
+ multiplier: number = 1,
+ flags?: TeamFlags,
+): number | undefined {
+ if (!HOSTED_MCP_CONCURRENCY_MODES.has(mode)) return undefined;
+ const tier = hostedMcpTier(mode, multiplier, flags);
+ if (!tier || concurrencyLimit >= tier.concurrency) return undefined;
+ return tier.concurrency;
+}
+
/**
* Autumn rate-limit multiplier granted to the hobby plan. Trusted agent
* traffic (a valid `__agentInterop` secret) is floored at this multiplier so a