Rate limit tool calls on the HTTP transport (#521)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: alistair3149

CHANGELOG.md

@@ -13,6 +13,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 
 ### Breaking changes
 
+- The HTTP transport now rate limits `tools/call`: each authenticated caller gets its own allowance (default 30 per second, burst 60) and anonymous callers share one (default 100 per second). A request over the limit is refused with `429` and a `Retry-After` header. Raise `MCP_RATE_LIMIT` / `MCP_RATE_LIMIT_BURST` / `MCP_RATE_LIMIT_ANONYMOUS` if you run high-throughput automation, or set `MCP_RATE_LIMIT=0` to disable.
 - The HTTP transport no longer forwards a caller's `Authorization: Bearer` header to MediaWiki. Such a request is refused with `401`, because a token minted by the wiki was not issued for this server. Use [hosted OAuth sign-in](docs/deployment.md#hosted-oauth-sign-in), or set `MCP_ALLOW_BEARER_PASSTHROUGH=true` to keep the old behaviour while you migrate; it is deprecated and will be removed. The server now warns at startup when a wiki requires a signed-in user but neither hosted sign-in nor forwarding is available, since no request could then succeed.
 - The server no longer advertises the wikis' own authorization servers, so a client can no longer discover where to mint a token to send here. Without hosted OAuth sign-in enabled, `/.well-known/oauth-protected-resource` now answers `404`, and `list-wikis` stops reporting each wiki's `authorizationServer`. Deployments running the hosted sign-in are unaffected.
 - The `Origin` header is now validated on every bind, and a request carrying an unlisted origin is refused with `403`. If you serve a browser-based client from a public bind, set `MCP_ALLOWED_ORIGINS` before upgrading. Clients that send no `Origin` header, which is most of them, are unaffected.

docs/deployment.md

@@ -49,7 +49,7 @@ Serve a single wiki for anonymous reads: no sign-in, no writes. Good for public
 
 `readOnly: true` together with `allowWikiManagement: false` hides the wiki-management tools (`add-wiki`, `remove-wiki`) and the six write tools (`create-page`, `update-page`, `delete-page`, `undelete-page`, `upload-file`, `upload-file-from-url`) from `tools/list`. What remains is an anonymous, read-only interface.
 
-Then run it with `MCP_TRANSPORT=http` behind a reverse proxy that terminates TLS and applies rate limiting (Cloudflare, nginx, and Caddy all work), then set the [Host and Origin allowlists](#security-checklist).
+Then run it with `MCP_TRANSPORT=http` behind a reverse proxy that terminates TLS (Cloudflare, nginx, and Caddy all work), then set the [Host and Origin allowlists](#security-checklist). The server itself [rate limits tool calls](#rate-limiting); IP-level limiting against anonymous floods still belongs at the proxy, which knows the caller's address when this server does not.
 
 ## Hosted OAuth sign-in
 
@@ -242,6 +242,9 @@ Set `MCP_TRANSPORT=http` to select this transport (the Docker image defaults to
 | `MCP_TRUSTED_HOSTS` | unset | Comma-separated **outbound** SSRF-guard exemptions for internal destinations (e.g. `mediawiki.svc`). See [Outbound SSRF guard](#outbound-ssrf-guard). |
 | `MCP_ALLOW_STATIC_FALLBACK` | unset | Allow HTTP startup when a wiki has static credentials, making them a shared fallback identity. See [Security checklist](#security-checklist). |
 | `MCP_ALLOW_BEARER_PASSTHROUGH` | unset | Deprecated. Forward a caller's `Authorization` header to MediaWiki as that caller. Without it such a request is refused with `401`. See [Per-request bearer token](#per-request-bearer-token-http-transport-deprecated). |
+| `MCP_RATE_LIMIT` | `30` | Sustained `tools/call` per second per authenticated caller. `0` disables rate limiting. See [Rate limiting](#rate-limiting). |
+| `MCP_RATE_LIMIT_BURST` | 2 × rate | How far a caller's burst can run ahead of the sustained rate. |
+| `MCP_RATE_LIMIT_ANONYMOUS` | `100` | Sustained `tools/call` per second across **all** anonymous callers combined (burst 2 × the rate, not separately tunable). `0` leaves anonymous traffic unlimited. |
 
 `MCP_MAX_REQUEST_BODY` matches nginx's `client_max_body_size 1m`. Raise it if `update-page` calls return 413 on legitimately large edits or your wiki has raised `$wgMaxArticleSize` (MediaWiki default 2 MB). Lower it for a tighter DoS guard.
 
@@ -308,6 +311,12 @@ wiki.example.org:8443         [::1]:3000                      localhost:3000
 
 A request carrying an `Origin` the server cannot parse at all is rejected with a 403. Requests with no `Origin` header pass, because non-browser MCP clients do not send one.
 
+### Rate limiting
+
+`tools/call` is rate limited per caller: each authenticated caller gets its own allowance (`MCP_RATE_LIMIT`, burst `MCP_RATE_LIMIT_BURST`), and all anonymous callers share one (`MCP_RATE_LIMIT_ANONYMOUS`). A request over the limit is refused with `429` and a `Retry-After` header, and never reaches the wiki. Only `tools/call` is limited; every other request, including subscription streams, passes untouched.
+
+The limiter is per-process — replicas each enforce their own allowance — and `mcp_rate_limited_total` on [`/metrics`](operations.md#metrics) counts refusals for tuning.
+
 ### v1 limitations
 
 These apply to the [hosted OAuth sign-in](#hosted-oauth-sign-in) setup:
@@ -335,9 +344,9 @@ The server accepts a standard OAuth 2.1 `Authorization: Bearer` header on each r
 Authorization: Bearer <oauth2-access-token>
 ```
 
-Use a MediaWiki OAuth2 access token obtained from `Special:OAuthConsumerRegistration/propose/oauth2` on the target wiki, with [Extension:OAuth](https://www.mediawiki.org/wiki/Extension:OAuth) installed. The server forwards it to MediaWiki as that caller's token, so writes are attributable and MediaWiki's per-user rate limits apply. A bearer is scoped to a single MediaWiki OAuth2 realm, and the server pins nothing across requests: one client can address wikis on different authorization servers by sending the right token per request. `list-wikis` reports each OAuth wiki's `authorizationServer`.
+Use a MediaWiki OAuth2 access token obtained from `Special:OAuthConsumerRegistration/propose/oauth2` on the target wiki, with [Extension:OAuth](https://www.mediawiki.org/wiki/Extension:OAuth) installed. The server forwards it to MediaWiki as that caller's token, so writes are attributable and MediaWiki's per-user rate limits apply. A bearer is scoped to a single MediaWiki OAuth2 realm, and the server pins nothing across requests: one client can address wikis on different authorization servers by sending the right token per request. While forwarding is enabled, `list-wikis` reports each OAuth wiki's `authorizationServer` so a caller can see which realm a wiki belongs to.
 
-The server no longer advertises the wikis' own authorization servers, so a client cannot discover where to mint such a token: obtain it yourself and configure it on the caller. Only [Hosted OAuth sign-in](#hosted-oauth-sign-in) publishes a protected-resource document, naming this server. While `MCP_ALLOW_BEARER_PASSTHROUGH=true` is set, a bearer-less request is challenged with `401` when no configured wiki is usable without a token; a deployment mixing OAuth and non-OAuth wikis still serves tokenless clients on the wikis that allow anonymous access.
+No OAuth discovery points at the wikis' authorization servers: the only protected-resource document is the one [Hosted OAuth sign-in](#hosted-oauth-sign-in) publishes, and it names this server. A client cannot discover where to mint a wiki token — obtain it yourself and configure it on the caller. While `MCP_ALLOW_BEARER_PASSTHROUGH=true` is set, a bearer-less request is challenged with `401` when no configured wiki is usable without a token; a deployment mixing OAuth and non-OAuth wikis still serves tokenless clients on the wikis that allow anonymous access.
 
 **Precedence:** request header (only while `MCP_ALLOW_BEARER_PASSTHROUGH=true`; otherwise refused with `401`) → `config.json` `token` → `config.json` `username`/`password` → anonymous. The HTTP transport refuses to start with static credentials in `config.json` unless `MCP_ALLOW_STATIC_FALLBACK=true` is set; see [the Security checklist](#security-checklist) for why.
 

docs/operations.md

@@ -90,6 +90,7 @@ Exposed series:
 - `mcp_inflight_requests` — gauge of `/mcp` requests currently being served. Subscription streams are excluded: they are held open by design.
 - `mcp_subscription_streams` — gauge of open change-notification streams (`subscriptions/listen`), the closest measure of connected clients.
 - `mcp_ready_failures_total` — counter of `/ready` probes that returned non-200.
+- `mcp_rate_limited_total{caller}` — counter of `tools/call` requests refused with `429`; the `caller` label is `caller` for authenticated callers and `anonymous` for the shared bucket. A rising `caller` series means authenticated callers hit `MCP_RATE_LIMIT`; a rising `anonymous` series means the shared backstop is engaging.
 - `mcp_proxy_store_upstream_tokens` — gauge of upstream MediaWiki tokens held in the hosted OAuth proxy store. This set grows with cumulative sign-ins over the process lifetime; watch it to size memory and the flush cost below.
 - `mcp_proxy_store_clients` — gauge of registered clients held in the hosted OAuth proxy store. FIFO-capped at 10,000, so this plateaus rather than growing without bound.
 - `mcp_proxy_store_flush_duration_seconds` — histogram of hosted-proxy store durable-flush durations (serialize + encrypt + write). Every upstream-token write flushes the whole store synchronously, so this scales with the token count above. Records successful flushes only.

src/auth/upstreamBearer.ts

@@ -93,28 +93,37 @@ async function performUpstreamRefresh(
 // UpstreamBearerError for a transient upstream failure, or a non-retryable one for
 // a dead refresh token. verifyAccessToken throws on an invalid/expired/mis-
 // audienced JWT; the caller maps that (and a missing upstream token) to a 401.
+export interface ResolvedUpstreamBearer {
+	accessToken: string;
+	// The proxy JWT's jti: stable per signed-in user and client across both proxy
+	// JWT refreshes and upstream token refreshes, which makes it the per-caller
+	// rate-limit key.
+	upstreamTokenId: string;
+}
+
 export async function resolveUpstreamBearer(
 	proxyJwt: string,
 	pc: ProxyConfig,
 	store: ProxyStore,
 	refresh: RefreshFn = defaultRefresh,
-): Promise<string> {
+): Promise<ResolvedUpstreamBearer> {
 	const { upstreamTokenId } = await verifyAccessToken(proxyJwt, pc);
 	const upstream = store.getUpstreamToken(upstreamTokenId);
 	if (!upstream) {
 		throw new Error('upstream token not found');
 	}
 	if (!(upstream.expiresAt <= Date.now() + UPSTREAM_REFRESH_SKEW_MS && upstream.refreshToken)) {
-		return upstream.accessToken;
+		return { accessToken: upstream.accessToken, upstreamTokenId };
 	}
 	const currentRefreshToken = upstream.refreshToken;
 	try {
-		return await coalesceUpstreamRefresh(upstreamTokenId, () =>
+		const accessToken = await coalesceUpstreamRefresh(upstreamTokenId, () =>
 			performUpstreamRefresh(upstreamTokenId, currentRefreshToken, pc, store, refresh),
 		);
+		return { accessToken, upstreamTokenId };
 	} catch (err) {
 		if (Date.now() < upstream.expiresAt) {
-			return upstream.accessToken;
+			return { accessToken: upstream.accessToken, upstreamTokenId };
 		}
 		throw new UpstreamBearerError(
 			classifyRefreshError(err) === 'retryable',

src/runtime/metrics.ts

@@ -18,6 +18,7 @@ type ProxyStoreStats = { readonly upstreamTokens: number; readonly clients: numb
 interface Recorder {
 	recordToolCall(input: RecordToolCallInput): void;
 	recordReadyFailure(): void;
+	recordRateLimited(caller: 'caller' | 'anonymous'): void;
 	setInFlightProvider(fn: () => number): void;
 	setSubscriptionStreamsProvider(fn: () => number): void;
 	recordStoreFlush(durationMs: number): void;
@@ -41,6 +42,7 @@ function makeDisabledRecorder(): Recorder {
 	return {
 		recordToolCall: () => {},
 		recordReadyFailure: () => {},
+		recordRateLimited: () => {},
 		setInFlightProvider: () => {},
 		setSubscriptionStreamsProvider: () => {},
 		recordStoreFlush: () => {},
@@ -84,6 +86,13 @@ function makeLiveRecorder(): Recorder {
 		registers: [registry],
 	});
 
+	const rateLimited = new Counter({
+		name: 'mcp_rate_limited_total',
+		help: 'Total tools/call requests refused with 429, labelled by whether the caller was authenticated.',
+		labelNames: ['caller'] as const,
+		registers: [registry],
+	});
+
 	new Gauge({
 		name: 'mcp_inflight_requests',
 		help: 'Number of requests under /mcp currently being served (subscription streams excluded).',
@@ -153,6 +162,9 @@ function makeLiveRecorder(): Recorder {
 		recordReadyFailure() {
 			readyFailures.inc();
 		},
+		recordRateLimited(caller) {
+			rateLimited.inc({ caller });
+		},
 		setInFlightProvider(fn) {
 			inFlightProvider = fn;
 		},
@@ -197,6 +209,10 @@ export function recordReadyFailure(): void {
 	recorder.recordReadyFailure();
 }
 
+export function recordRateLimited(caller: 'caller' | 'anonymous'): void {
+	recorder.recordRateLimited(caller);
+}
+
 export function setInFlightProvider(fn: () => number): void {
 	recorder.setInFlightProvider(fn);
 }

src/transport/errorCodes.ts

@@ -7,3 +7,4 @@
 export const AUTHENTICATION_REQUIRED_ERROR_CODE = -31001;
 export const UPSTREAM_UNAVAILABLE_ERROR_CODE = -31002;
 export const PAYLOAD_TOO_LARGE_ERROR_CODE = -31003;
+export const RATE_LIMITED_ERROR_CODE = -31004;

src/transport/httpConfig.ts

@@ -1,3 +1,5 @@
+import type { RateLimitSettings } from './rateLimit.ts';
+
 export interface HttpConfig {
 	host: string;
 	port: number;
@@ -7,6 +9,8 @@ export interface HttpConfig {
 	// request", which is the safe default rather than an absent control.
 	allowedOrigins: string[];
 	maxRequestBody: string;
+	// null when the operator disabled rate limiting with MCP_RATE_LIMIT=0.
+	rateLimit: RateLimitSettings | null;
 	warnings: string[];
 }
 
@@ -109,11 +113,58 @@ function resolveMaxRequestBody(): { value: string; warning?: string } {
 	return { value: trimmed };
 }
 
+const DEFAULT_RATE_LIMIT = 30;
+const DEFAULT_ANONYMOUS_RATE_LIMIT = 100;
+
+// Accepts a non-negative number; undefined means unset, null means unparseable.
+function parseRateValue(raw: string | undefined): number | null | undefined {
+	if (raw === undefined || raw.trim() === '') {
+		return undefined;
+	}
+	const parsed = Number(raw);
+	return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
+}
+
+// Rate limiting for tools/call, on by default. MCP_RATE_LIMIT=0 disables it
+// entirely; MCP_RATE_LIMIT_ANONYMOUS=0 leaves anonymous traffic unlimited while
+// signed-in callers stay limited. Bursts default to twice the sustained rate,
+// the headroom an agent firing a batch of calls needs; only the per-caller
+// burst is separately tunable.
+function resolveRateLimit(): { value: RateLimitSettings | null; warnings: string[] } {
+	const warnings: string[] = [];
+	const read = (name: string, fallback: number): number => {
+		const parsed = parseRateValue(process.env[name]);
+		if (parsed === null) {
+			warnings.push(
+				`${name}=${process.env[name]} is not a non-negative number; using default ${fallback}`,
+			);
+			return fallback;
+		}
+		return parsed ?? fallback;
+	};
+	const rate = read('MCP_RATE_LIMIT', DEFAULT_RATE_LIMIT);
+	if (rate === 0) {
+		return { value: null, warnings };
+	}
+	const burst = read('MCP_RATE_LIMIT_BURST', rate * 2);
+	const anonymousRate = read('MCP_RATE_LIMIT_ANONYMOUS', DEFAULT_ANONYMOUS_RATE_LIMIT);
+	return {
+		value: {
+			ratePerSecond: rate,
+			burst: Math.max(1, burst),
+			anonymousRatePerSecond: anonymousRate,
+			anonymousBurst: Math.max(1, anonymousRate * 2),
+		},
+		warnings,
+	};
+}
+
 export function resolveHttpConfig(): HttpConfig {
 	const host = resolveHost();
 	const port = resolvePort();
 	const body = resolveMaxRequestBody();
-	const warnings: string[] = [];
+	const rateLimit = resolveRateLimit();
+	const warnings: string[] = [...rateLimit.warnings];
 	if (body.warning) {
 		warnings.push(body.warning);
 	}
@@ -132,6 +183,7 @@ export function resolveHttpConfig(): HttpConfig {
 		allowedHosts: resolveAllowedHosts(),
 		allowedOrigins: resolveAllowedOrigins(host, port),
 		maxRequestBody: body.value,
+		rateLimit: rateLimit.value,
 		warnings,
 	};
 }