MCP Overhead alert (when your MCP servers cost too much)
An amber inbox card that fires when the MCP servers configured for your sessions add up to too much overhead — a tool-definition token estimate past its limit, too much memory while sessions run, or servers you never actually use. Covers the three independent trip conditions and the one global rule behind them.
On this page
What it is
Amber inbox card that fires when the MCP servers configured across your sessions add up to too much overhead. It is the MCP analogue of the Doc Token Alert: same inbox-card + snooze + Settings-limit shape, but global (MCP config is not per-project in Omniscio, so there is exactly one rule) and with three independent trip legs instead of one.
What it watches
Every MCP server you have enabled brings tool definitions of its own (a token cost this alert estimates) and, while a session is running, uses memory. Claude Code's tool search is on by default, and it defers those definitions: each server's tool names and instructions load at session start, and a definition loads in full only when Claude goes looking for it — unless the tool or its server is marked to load upfront. Claude Code falls back to loading definitions upfront in several other situations too — for example on models earlier than Opus 4 and Sonnet 4, on the earlier models on Google Cloud's Agent Platform (whose serving stack rejects the feature), on Microsoft Foundry deployments hosted on Azure, and wherever tool search has been switched off. In the ordinary case a large server stack costs far less context than the definitions alone would suggest (Anthropic's Claude Code MCP documentation is the reference for when tool search applies). The checker watches every server that would actually load — your ~/.claude.json servers, Omniscio's custom-server registry, and Omniscio's own built-in servers that you have switched on. A built-in you have switched off is never counted, and neither is one Omniscio keeps off by product decision (Google Drive's server, which needs a scope the app does not request). It fires when any of these crosses its limit:
- Estimated tokens — a heuristic estimate of how much the servers' tool definitions would weigh if they all loaded. Always labeled an estimate: Omniscio never starts a server to count its real tool-definition tokens (that would stall sessions for a minute+, the same reason spawns never pass
--mcp-config). - Active-session RAM — measured memory (MB) of live MCP child processes, summed from the Resources sampler. Best-effort: when no session is active (or no fresh sample exists)
ramMbisnulland this leg is simply skipped — it never blocks the other two. - Unused servers — servers with no tool call in the usage window (from the
tool_invocationsscanner): never used at all, or last used longer ago than the window. The most reliable "wasted weight" signal, and the one that ships at a limit of 1 — a single server you have stopped using is enough for the card to say so. For an install's first 30 days this leg stays silent, because with that little history every server looks unused; the token and RAM legs are real from day one and are never held back.
A limit of 0 disables that leg. The alert fires when any enabled leg trips (token OR RAM OR unused).
Where to find it
The alert arrives as an amber card in your inbox, titled "MCP overhead over budget", alongside your other alerts — open it for the numbers and your options. (It is not grouped under the MCP Servers sidebar entry; that panel is for managing your servers, not for this alert.) Its limits live in Settings → Notifications → MCP Overhead.
How it behaves
Honesty contract
- Estimate: the token figure (clearly marked
est.). - Measured: server count, active-session RAM, and per-server usage (call counts, "never used").
A non-technical user never sees a guess dressed up as a fact.
The card
The card is titled "MCP overhead over budget". Opening it shows the headline estimate (red when over the token limit), active-session RAM (or "Not measured — no active session"), the unused/total server count, the configured limits, and a per-server breakdown (each server's estimated tokens, source, call count, and a "never used" flag). Three actions:
- Archive — the card's own Archive button (top of the card; also the keyboard
Eshortcut, middle-click, bulk archive, or an inbox rule) acknowledges the overhead at its current size (sticky-to-size, tiered re-alert: won't re-fire until a tripping metric grows past the dismissed value by the re-alert growth %, or the re-alert cadence elapses). - Manage MCP servers — opens the MCP Servers panel so you can turn off the dead weight.
- Start session — the universal button every alert card carries, for asking an agent to help instead.
The card also supports the universal inbox snooze, and you can mute MCP Overhead alerts entirely — from the card, or from Settings → Notifications → Alert types.
Settings
Settings → Notifications → MCP Overhead holds the single global rule: a master enable toggle plus tunable limits (estimated-token limit, active-RAM MB limit, unused-server limit) and the two re-alert knobs (growth %, cadence days). The unused limit ships at 1; set it to 0 to switch that leg off entirely, or to any higher number to be told only when several servers have gone quiet. The master switch is the enabled flag on the seeded 'global' rule — there is no AppSettings field.
Related
- mcp-servers.md — the servers this alert is measuring, and how to add or trim them.
- doc-token-alert.md — the same kind of alert for documentation overhead rather than MCP tool definitions.
Last verified 2026-10-23