Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(mcp): charge the per-IP throttle per JSON-RPC message

Yudhi Armyndharise6f7289bbf8b
diff --git a/.env.example b/.env.example
index bc3793bf7..dd409f25c 100644
--- a/.env.example
+++ b/.env.example
@@ -701,7 +701,7 @@ WEBHOOK_SSRF_PROTECT=true
# MCP_RATE_LIMIT_WINDOW_MS=60000 # window size in ms (default 60000 = 1 min)
# Pre-auth, per-IP sliding-window throttle for the /mcp mount (gates invalid-key requests before
# key validation, since the raw mount bypasses the global throttler). Same fallback rules.
-# MCP_IP_RATE_LIMIT_MAX=120 # max requests per IP per window (default 120)
+# MCP_IP_RATE_LIMIT_MAX=120 # max JSON-RPC messages per IP per window (default 120)
# MCP_IP_RATE_LIMIT_WINDOW_MS=60000 # window size in ms (default 60000 = 1 min)
# =============================================================================
diff --git a/docs/06-api-specification.md b/docs/06-api-specification.md
index c737c74c7..e740b9630 100644
--- a/docs/06-api-specification.md
+++ b/docs/06-api-specification.md
@@ -6208,6 +6208,7 @@ Key facts:
- Gated by **`MCP_ENABLED=true`**. When off, the module/route is never mounted and `POST /mcp` returns `404`.
- MCP is **read-only by default**: only read-tier tools are registered unless you set `MCP_READONLY=false` to expose write tools. Per-key sliding-window rate limit: `MCP_RATE_LIMIT_MAX` (default 60) per `MCP_RATE_LIMIT_WINDOW_MS` (default 60000).
- Stateless transport (no SSE/session id for normal calls).
+- Pre-auth per-IP throttle: `MCP_IP_RATE_LIMIT_MAX` (default 120) JSON-RPC messages per `MCP_IP_RATE_LIMIT_WINDOW_MS` (default 60000). Each element of a batch counts; an over-budget request gets HTTP `429` with a JSON-RPC error body and runs none of its messages, but still spends whatever budget the IP had left.
**Request body** — JSON-RPC 2.0 envelope (validated by the MCP SDK, **not** the Nest ValidationPipe)
diff --git a/docs/24-mcp-integration.md b/docs/24-mcp-integration.md
index a9b3cef08..92b0280ee 100644
--- a/docs/24-mcp-integration.md
+++ b/docs/24-mcp-integration.md
@@ -176,7 +176,11 @@ only when an agent genuinely needs to send messages / mutate state.
missing/invalid key would otherwise reach a DB lookup unthrottled). It keys on the
resolved client IP (honoring `TRUSTED_PROXIES`) and is tuned with `MCP_IP_RATE_LIMIT_MAX`
(default `120`) and `MCP_IP_RATE_LIMIT_WINDOW_MS` (default `60000`), with the same
- fallback rules — independent of the per-key vars.
+ fallback rules, independent of the per-key vars. It counts JSON-RPC messages, not HTTP
+ requests: each element of a batch spends one unit, and a batch larger than the
+ remaining budget is refused whole with a `429`. None of its messages run, but the
+ refusal still spends whatever budget was left, so the IP is at the cap until the
+ window slides.
- **Response parity.** Tools reuse the REST response DTOs, so sensitive fields the REST
API strips (e.g. webhook HMAC secrets and custom headers, session proxy URLs and engine
config) are **not** exposed over MCP.
@@ -192,7 +196,7 @@ MCP_ENABLED=true npm run start:prod # or set MCP_ENABLED in your .env / compos
MCP_READONLY=false # expose write tools (default is read-only when unset)
MCP_RATE_LIMIT_MAX=60 # max tool calls per key per window (default 60)
MCP_RATE_LIMIT_WINDOW_MS=60000 # sliding window in ms (default 60000 = 1 min)
-MCP_IP_RATE_LIMIT_MAX=120 # pre-auth per-IP request cap per window (default 120)
+MCP_IP_RATE_LIMIT_MAX=120 # pre-auth per-IP message cap per window (default 120)
MCP_IP_RATE_LIMIT_WINDOW_MS=60000 # per-IP window in ms (default 60000 = 1 min)
```
diff --git a/src/modules/mcp/mcp.server.spec.ts b/src/modules/mcp/mcp.server.spec.ts
index 8d18a9be5..c52a0f922 100644
--- a/src/modules/mcp/mcp.server.spec.ts
+++ b/src/modules/mcp/mcp.server.spec.ts
@@ -76,7 +76,8 @@ describe('resolveMcpReadOnly (secure-by-default MCP read-only flag)', () => {
// after key validation, so a missing/invalid-key flood would otherwise reach a DB lookup unthrottled.
// createIpThrottle gates by resolved client IP BEFORE auth and answers with a JSON-RPC 429.
describe('createIpThrottle (pre-auth per-IP MCP throttle)', () => {
- const makeReq = (ip: string): Request => ({ socket: { remoteAddress: ip }, headers: {} }) as unknown as Request;
+ const makeReq = (ip: string, body?: unknown): Request =>
+ ({ socket: { remoteAddress: ip }, headers: {}, body }) as unknown as Request;
type ResMock = { status: jest.Mock; json: jest.Mock; statusCode?: number; body?: unknown };
const makeRes = (): ResMock => {
@@ -115,6 +116,44 @@ describe('createIpThrottle (pre-auth per-IP MCP throttle)', () => {
throttle(makeReq('2.2.2.2'), makeRes() as unknown as Response, next);
expect(next).toHaveBeenCalledWith();
});
+
+ // Every element of a JSON-RPC batch is dispatched (and each tools/call runs its own key lookup and
+ // auth-failure audit), so the budget is charged per message, not per HTTP request.
+ const call = { jsonrpc: '2.0', id: 1, method: 'tools/call', params: { name: 'SessionFindAll', arguments: {} } };
+
+ it('rejects a batch larger than the remaining per-IP budget', () => {
+ const throttle = createIpThrottle(new KeyRateLimiter(2, 60_000));
+ const next = jest.fn();
+ const res = makeRes();
+ throttle(makeReq('1.2.3.4', [call, call, call]), res as unknown as Response, next);
+ expect(next).not.toHaveBeenCalled();
+ expect(res.status).toHaveBeenCalledWith(429);
+ expect((res.body as { error?: { code?: number } }).error?.code).toBe(-32000);
+ });
+
+ it('charges each batch element, so the next request after a full batch is throttled', () => {
+ const throttle = createIpThrottle(new KeyRateLimiter(2, 60_000));
+ const next1 = jest.fn();
+ throttle(makeReq('1.2.3.4', [call, call]), makeRes() as unknown as Response, next1);
+ expect(next1).toHaveBeenCalledWith();
+
+ const next2 = jest.fn();
+ const res2 = makeRes();
+ throttle(makeReq('1.2.3.4', call), res2 as unknown as Response, next2);
+ expect(next2).not.toHaveBeenCalled();
+ expect(res2.status).toHaveBeenCalledWith(429);
+ });
+
+ it('charges an empty batch as one message', () => {
+ const throttle = createIpThrottle(new KeyRateLimiter(1, 60_000));
+ const next1 = jest.fn();
+ throttle(makeReq('1.2.3.4', []), makeRes() as unknown as Response, next1);
+ expect(next1).toHaveBeenCalledWith();
+
+ const next2 = jest.fn();
+ throttle(makeReq('1.2.3.4', call), makeRes() as unknown as Response, next2);
+ expect(next2).not.toHaveBeenCalled();
+ });
});
// MCP auth is raw Express (outside the Nest guard pipeline) so it bypasses the global ApiKeyGuard's
@@ -202,6 +241,7 @@ describe('mountMcpServer (raw-Express request-handling path)', () => {
tool: AnyToolDescriptor;
authService: { validateApiKey: jest.Mock; hasPermission: jest.Mock };
auditService: { logWarn: jest.Mock };
+ adapter: { post: jest.Mock };
}
const mount = (): Harness => {
@@ -231,10 +271,10 @@ describe('mountMcpServer (raw-Express request-handling path)', () => {
{ readOnly: false },
auditService as unknown as AuditService,
);
- // adapter.post received [createIpThrottle(...), express.json(...), mcpHandler]; the tests drive
+ // adapter.post received [express.json(...), createIpThrottle(...), mcpHandler]; the tests drive
// the terminal handler directly with a pre-parsed body, as the file's middleware harness does.
const routeHandler = routeHandlers[routeHandlers.length - 1] as Harness['routeHandler'];
- return { routeHandler, tool, authService, auditService };
+ return { routeHandler, tool, authService, auditService, adapter };
};
type ResMock = { on: jest.Mock; status: jest.Mock; json: jest.Mock; headersSent: boolean };
@@ -268,6 +308,13 @@ describe('mountMcpServer (raw-Express request-handling path)', () => {
return mockRegisteredTools[0].callback;
};
+ it('parses the body before the per-IP throttle so a batch is charged per message', () => {
+ const h = mount();
+ const [path, parser] = h.adapter.post.mock.calls[0] as unknown[];
+ expect(path).toBe('/mcp');
+ expect((parser as { name?: string }).name).toBe('jsonParser');
+ });
+
it('dispatches the request to transport.handleRequest with the parsed body', async () => {
const h = mount();
const body = {
diff --git a/src/modules/mcp/mcp.server.ts b/src/modules/mcp/mcp.server.ts
index bde30cf3a..cb8a47ba0 100644
--- a/src/modules/mcp/mcp.server.ts
+++ b/src/modules/mcp/mcp.server.ts
@@ -172,8 +172,13 @@ export interface MountMcpServerOptions {
export function createIpThrottle(ipRateLimiter: KeyRateLimiter): RequestHandler {
return (req, res, next) => {
const ip = resolveClientIp(req, readTrustedProxies());
+ // The unit of work is the JSON-RPC message, not the HTTP request: the transport dispatches every
+ // element of a batch, and each tools/call element runs its own key lookup and auth-failure audit.
+ // An over-budget batch throws on the first check past the cap, so a huge array costs at most
+ // `max + 1` checks.
+ const messages = Array.isArray(req.body) ? Math.max(1, req.body.length) : 1;
try {
- ipRateLimiter.check(ip);
+ for (let i = 0; i < messages; i++) ipRateLimiter.check(ip);
next();
} catch (err) {
const status = err instanceof HttpException ? err.getStatus() : 429;
@@ -244,12 +249,13 @@ export function mountMcpServer(
const adapter = httpAdapter as unknown as { post: (path: string, ...handlers: RequestHandler[]) => unknown };
// The route throttle gates the auth DB lookup and per-request MCP server/transport construction. The
// process-wide capped json() in main.ts runs first for all routes; this route-level parser is a
- // defensive fallback and no-ops once the global parser has consumed the body.
+ // defensive fallback and no-ops once the global parser has consumed the body. It sits before the
+ // throttle so the throttle always sees a parsed body and can charge a batch per message.
// `inflate: false` matches the global parsers: a compressed body is refused by the budget
// middleware long before this runs, and this keeps the fallback from becoming the one parser that
// would still gunzip an unaccounted body if that ordering ever changed.
// `limit` mirrors the same global cap for the same reason: without it a middleware reorder would
// silently leave this mount uncapped.
const bodyLimit = resolveBodyLimit(process.env.BODY_SIZE_LIMIT);
- adapter.post(basePath, createIpThrottle(ipRateLimiter), express.json({ limit: bodyLimit, inflate: false }), handler);
+ adapter.post(basePath, express.json({ limit: bodyLimit, inflate: false }), createIpThrottle(ipRateLimiter), handler);
}