@frontmcp/guard

Rate limiting, concurrency limits, execution timeouts and IP filtering for FrontMCP. @frontmcp/sdk uses it for the throttle option of @FrontMcp and the rateLimit, concurrency and timeout options of tools and agents, so in a FrontMCP server you set those options and don't import this package. Install it directly to use the limiters on their own. They keep their counters behind the StorageAdapter interface of @frontmcp/utils, so they work with memory, Redis, Vercel KV, Upstash and Cloudflare KV storage.

Install

npm install @frontmcp/guard @frontmcp/lazy-zod zod

@frontmcp/lazy-zod is a peer dependency (the configuration schemas use it), and it needs zod 4. Node.js 24 or later. A FrontMCP server doesn't need this install: @frontmcp/sdk depends on @frontmcp/guard and re-exports everything in it.

Usage

In a FrontMCP server

Set limits on a tool, and defaults for the whole server. The SDK passes these options to this package:

import { App, FrontMcp, Tool, ToolContext } from '@frontmcp/sdk';

@Tool({
  name: 'export_tickets',
  description: 'Export every ticket as CSV. At most 2 exports an hour per caller, one at a time.',
  inputSchema: {},
  rateLimit: { maxRequests: 2, windowMs: 60 * 60_000, partitionBy: 'userId' },
  concurrency: { maxConcurrent: 1, queueTimeoutMs: 5_000 },
  timeout: { executeMs: 30_000 },
})
class ExportTickets extends ToolContext {
  async execute() {
    return { csv: 'id,title' };
  }
}

@App({ id: 'help-desk', name: 'Help Desk', tools: [ExportTickets] })
class HelpDeskApp {}

@FrontMcp({
  info: { name: 'help-desk', version: '1.0.0' },
  apps: [HelpDeskApp],
  throttle: {
    enabled: true,
    defaultRateLimit: { maxRequests: 60, windowMs: 60_000, partitionBy: 'userId' },
    global: { maxRequests: 1_000, windowMs: 60_000, partitionBy: 'ip' },
    ipFilter: { denyList: ['192.0.2.0/24'] },
  },
})
export default class Server {}

Guard options covers what each option does in a server, and the error a caller gets back.

On its own

createGuardManager builds a GuardManager from one configuration object:

import { createGuardManager } from '@frontmcp/guard';

const guard = await createGuardManager({
  config: {
    enabled: true,
    defaultRateLimit: { maxRequests: 100, windowMs: 60_000, partitionBy: 'session' },
    defaultConcurrency: { maxConcurrent: 5 },
    ipFilter: { denyList: ['10.0.0.0/8'], defaultAction: 'allow' },
  },
});

const ipResult = guard.checkIpFilter('203.0.113.5');
if (ipResult && !ipResult.allowed) throw new Error('IP refused');

const rateLimit = await guard.checkRateLimit('my-tool', undefined, { sessionId: 'sess-123' });
if (!rateLimit.allowed) throw new Error(`Retry after ${rateLimit.retryAfterMs}ms`);

const ticket = await guard.acquireSemaphore('my-tool', undefined, { sessionId: 'sess-123' });
if (!ticket) throw new Error('No free slot');
try {
  // ... do the work ...
} finally {
  await ticket.release();
}

await guard.destroy();

Without a storage configuration the manager keeps its counters in memory, one set per process, and warns about it through logger when you pass one.

Rate limiting

SlidingWindowRateLimiter uses the sliding window counter algorithm. It keeps two adjacent fixed-window counters and weights the previous window's count by how much of that window still falls within windowMs of now. That approximates a true sliding window with constant storage per key, without the bursts a single fixed window allows at its edges. Windows are aligned to the clock.

The class takes a storage adapter. createMemoryStorage and the other adapters come from @frontmcp/utils, which is installed with this package; add it to your own dependencies to import it.

import { SlidingWindowRateLimiter } from '@frontmcp/guard';
import { createMemoryStorage } from '@frontmcp/utils';

const storage = createMemoryStorage();
await storage.connect();
const limiter = new SlidingWindowRateLimiter(storage);

const result = await limiter.check(
  'user:42', // key
  100, // max requests
  60_000, // window in ms
);

if (!result.allowed) {
  console.log(`Rate limited. Retry after ${result.retryAfterMs}ms`);
}

An allowed check counts the request. RateLimitResult has:

• allowed: whether the request can proceed
• remaining: approximate requests left in this window
• resetMs: milliseconds until the current window ends
• retryAfterMs: when blocked, how long to wait

reset(key, windowMs) deletes a key's counters.

Concurrency control

DistributedSemaphore limits how many executions run at once for a key. The key has maxConcurrent slots, each stored as its own key. An execution claims a free slot with a write-if-absent that carries its ticket's time to live (TTL, 300 seconds by default), and renews the TTL every third of it until it calls release(). So the slot is held for as long as the execution runs, and the TTL only frees the slot of a process that died without releasing it. Releasing or renewing only touches a slot that still holds the same ticket, so the storage needs an atomic compare-and-delete and compare-and-expire: memory, Redis, Upstash or Vercel KV. With another adapter, acquire() throws GuardStorageUnsupportedError, and createGuardManager does too when globalConcurrency or defaultConcurrency is set.

When every slot is taken, a caller can wait for one, polling every 100 ms at first and backing off to once a second. If the storage supports publish/subscribe (memory, Redis, and Upstash with publish/subscribe turned on), a released slot wakes waiting callers at once.

import { DistributedSemaphore } from '@frontmcp/guard';
import { createMemoryStorage } from '@frontmcp/utils';

const storage = createMemoryStorage();
await storage.connect();
const semaphore = new DistributedSemaphore(storage, 300 /* ticket TTL in seconds */);

const ticket = await semaphore.acquire(
  'my-tool:global', // key
  5, // max concurrent
  10_000, // how long to wait for a slot, in ms (0 = don't wait)
  'my-tool', // name used in error messages
);

if (ticket) {
  try {
    // ... do the work ...
  } finally {
    await ticket.release();
  }
}

acquire returns null when every slot is taken and the wait is 0, and throws QueueTimeoutError when it waited and no slot freed up. getActiveCount(key) returns the number of taken slots, and forceReset(key) frees every slot.

Timeout

withTimeout runs an async function with a deadline. It passes the function an AbortSignal that is aborted when time runs out, and rejects with ExecutionTimeoutError. The function keeps running unless it listens to the signal.

import { withTimeout } from '@frontmcp/guard';

const response = await withTimeout(
  (signal) => fetch('https://api.example.com/data', { signal }),
  5_000, // timeout in ms
  'fetch-data', // name used in error messages
);

IP filtering

IpFilter checks a client IP against allow and deny lists of addresses and CIDR ranges, IPv4 and IPv6. An IPv4-mapped IPv6 address (::ffff:192.168.1.1, which a dual-stack socket reports for an IPv4 client) matches as the IPv4 address it maps. Matching uses bigint arithmetic, so it's exact across the whole IPv6 address space.

The deny list is checked first: an IP on it is refused, whatever the allow list says. Then the allow list, then defaultAction. An allow list on its own refuses nothing: add defaultAction: 'deny' to refuse every other address. A missing or unparseable IP matches no rule and gets defaultAction, so check(undefined) refuses under defaultAction: 'deny'.

import { IpFilter } from '@frontmcp/guard';

const filter = new IpFilter({
  allowList: ['192.168.0.0/16'],
  denyList: ['192.168.1.100'],
  defaultAction: 'deny',
});

const result = filter.check('192.168.2.50');
// { allowed: true, reason: 'allowlisted', matchedRule: '192.168.0.0/16' }

const blocked = filter.check('192.168.1.100');
// { allowed: false, reason: 'denylisted', matchedRule: '192.168.1.100' }

isAllowListed(ip) tells you whether an IP is on the allow list, for example to skip rate limiting for trusted addresses.

Partition keys

A partition key decides which calls share a rate-limit count or a set of concurrency slots:

You can also pass a function of the PartitionKeyContext, which has sessionId (always set) and optional clientIp and userId:

import type { RateLimitConfig } from '@frontmcp/guard';

const config: RateLimitConfig = {
  maxRequests: 100,
  windowMs: 60_000,
  partitionBy: (ctx) => (ctx.userId ? `user:${ctx.userId}` : `session:${ctx.sessionId}`),
};

Guard manager

GuardManager combines rate limiting, concurrency control and IP filtering behind one configuration. createGuardManager creates its storage and connects it.

The configuration has two levels:

• Global, applied to every request: global (a rate limit) and globalConcurrency.
• Default, applied to an entity that doesn't pass its own: defaultRateLimit, defaultConcurrency, defaultTimeout.

A configuration passed for one entity replaces the default; it doesn't add to it.

import { createGuardManager } from '@frontmcp/guard';

const guard = await createGuardManager({
  config: {
    enabled: true,
    storage: { type: 'redis', redis: { config: { host: 'localhost', port: 6379 } } },
    keyPrefix: 'myapp:guard:',
    global: { maxRequests: 1000, windowMs: 60_000, partitionBy: 'ip' },
    globalConcurrency: { maxConcurrent: 50, partitionBy: 'global' },
    defaultRateLimit: { maxRequests: 100, windowMs: 60_000, partitionBy: 'session' },
    defaultConcurrency: { maxConcurrent: 10, queueTimeoutMs: 5_000 },
    defaultTimeout: { executeMs: 30_000 },
    ipFilter: {
      denyList: ['10.0.0.0/8'],
      allowList: ['10.0.1.0/24'],
      defaultAction: 'allow',
    },
  },
  logger: console,
});

const context = { sessionId: 'sess-1', clientIp: '203.0.113.5' };
const globalRateLimit = await guard.checkGlobalRateLimit(context);
const entityRateLimit = await guard.checkRateLimit('my-tool', undefined, context);
const globalTicket = await guard.acquireGlobalSemaphore(context);
const ticket = await guard.acquireSemaphore('my-tool', undefined, context);

await ticket?.release();
await globalTicket?.release();
await guard.destroy();

The manager doesn't apply defaultTimeout itself: read it from guard.config and pass it to withTimeout.

Configuration reference

GuardConfig

RateLimitConfig

ConcurrencyConfig

TimeoutConfig

IpFilterConfig

Storage

The guard keeps everything behind the StorageAdapter interface of @frontmcp/utils. createGuardManager builds one from storage with createStorage:

storage is a StorageConfig, such as { type: 'redis', redis: { config: { host, port } } } or { type: 'redis', redis: { url } }. Without type it's 'auto', which picks a backend from environment variables.

storage.fallback decides what happens when the backend can't be reached. With 'error', the default in production (NODE_ENV=production), createGuardManager rejects with GuardStorageUnavailableError: rate limits fail closed. With 'memory', the default elsewhere, it starts with per-instance counters and logs a warning. The same setting applies if the backend stops answering later: each check then fails with GuardStorageUnavailableError, or, with 'memory', is served from per-instance counters until the backend answers again.

Keys are written as <keyPrefix><entity>:<partition>:<kind>:… with a single : after the prefix, for example mcp:guard:export_tickets:global:rl:…. Before 1.8.6 the default prefix produced mcp:guard::export_tickets:…. Counters written by an older instance aren't read by a newer one, so limits briefly split during a rolling deploy.

Errors

Every error extends GuardError, which has a machine-readable code and an HTTP statusCode. instanceof GuardError also recognizes an error from another copy of this package in the same process.

import { ExecutionTimeoutError, withTimeout } from '@frontmcp/guard';

try {
  await withTimeout(() => new Promise((resolve) => setTimeout(resolve, 10_000)), 5_000, 'slow-op');
} catch (err) {
  if (err instanceof ExecutionTimeoutError) {
    console.log(err.code); // 'EXECUTION_TIMEOUT'
    console.log(err.statusCode); // 408
    console.log(err.timeoutMs); // 5000
  }
}

API reference

Everything is exported from the package root.

Docs

• Guard options: rateLimit, concurrency, timeout and throttle in a FrontMCP server, and the building blocks this package exports
• Limiting and timing out calls: the same options, step by step
• Error classes: the errors a caller gets back

Related packages

• @frontmcp/sdk: the framework that applies these limits to tools and agents
• @frontmcp/utils: the storage adapters the guard keeps its counters in

Contributing

Source: libs/guard. Issues and pull requests are welcome; see CONTRIBUTING.md.

License

Apache-2.0. See LICENSE.