Invalid MCP_MAX_SUBSCRIPTIONS; using the default of ${DEFAUL

Error message

Invalid MCP_MAX_SUBSCRIPTIONS; using the default of ${DEFAULT_MAX_SUBSCRIPTIONS}.

What it means

This is a console warning (not a thrown exception) emitted by getMaxSubscriptions() in packages/mcp/src/lib/subscriptions.ts when the MCP_MAX_SUBSCRIPTIONS environment variable is set but cannot be parsed as a positive safe integer. The function falls back to DEFAULT_MAX_SUBSCRIPTIONS and continues, so subscriptions still work but the custom limit is ignored. It exists to surface misconfiguration instead of silently accepting a bad value.

Source

Thrown at packages/mcp/src/lib/subscriptions.ts:10

// 16k stayed near baseline latency in Docker; 32,768 raised tools/list p95 to ~39 ms.
export const DEFAULT_MAX_SUBSCRIPTIONS = 16_000;

export function getMaxSubscriptions(value = process.env.MCP_MAX_SUBSCRIPTIONS): number {
  if (value === undefined) return DEFAULT_MAX_SUBSCRIPTIONS;

  const parsed = Number(value);
  if (Number.isSafeInteger(parsed) && parsed > 0) return parsed;

  console.warn(`Invalid MCP_MAX_SUBSCRIPTIONS; using the default of ${DEFAULT_MAX_SUBSCRIPTIONS}.`);
  return DEFAULT_MAX_SUBSCRIPTIONS;
}

View on GitHub (pinned to c05c71c5fd)

Solutions

Set MCP_MAX_SUBSCRIPTIONS to a whole positive integer string, e.g. MCP_MAX_SUBSCRIPTIONS=1000
Unset/delete MCP_MAX_SUBSCRIPTIONS entirely if the default limit is acceptable
Trim whitespace and remove quotes/suffixes from the value in your env file or secret manager
In code, pre-validate with Number.isSafeInteger(Number(value)) && Number(value) > 0 before relying on the env var

Example fix

// before (.env)
MCP_MAX_SUBSCRIPTIONS=1000x

// after (.env)
MCP_MAX_SUBSCRIPTIONS=1000

Defensive patterns

Strategy: validation

Validate before calling

function isValidMaxSubscriptions(value) {
  const n = Number(value);
  return Number.isSafeInteger(n) && n > 0;
}
const raw = process.env.MCP_MAX_SUBSCRIPTIONS;
if (raw !== undefined && !isValidMaxSubscriptions(raw)) {
  throw new Error(`MCP_MAX_SUBSCRIPTIONS must be a positive integer, got: ${raw}`);
}

Type guard

function isPositiveSafeInt(value: unknown): value is number {
  return typeof value === 'number'
    ? Number.isSafeInteger(value) && value > 0
    : typeof value === 'string' && /^\d+$/.test(value.trim()) && Number.isSafeInteger(Number(value)) && Number(value) > 0;
}

Prevention

Validate environment variables at process startup with a schema library (e.g. zod) so bad values fail fast
Always store numeric env vars as unquoted plain integers in .env / deployment configs
Check container/CI logs for this warning when bumping subscription limits — it indicates the new value was ignored
Add a startup assertion or smoke test that reads the resolved limit via getMaxSubscriptions() and asserts it matches the intended value

When it happens

Trigger: Setting MCP_MAX_SUBSCRIPTIONS to a non-numeric string (e.g. 'ten'), a zero or negative number (e.g. '0', '-5'), a decimal (e.g. '2.5' → NaN-safe check fails since Number.isSafeInteger(2.5) is false), or an out-of-range/Infinity value, then calling getMaxSubscriptions() (indirectly via mcpHandler).

Common situations: Typo or quoting mistakes in .env / docker-compose / CI environment files; YAML or shell configs quoting the value as a string with stray characters ('10\n', '"10"' is fine but '10 ' may parse oddly); Kubernetes ConfigMap values with whitespace; someone setting the var to a percentage or descriptive word expecting it to be interpreted.

Understand the failure class

Background: "is not a valid" / "Invalid ... value" environment variable errors: how libraries validate env vars and what to do when they reject yours — this error's family across 48 libraries.

Related errors

AI-assisted analysis of upstash/context7@c05c71c5fd (2026-09-02). Data as JSON: /api/errors/99ed4936d2f7a6f6. Report an issue: GitHub.