Skip to main content
Glama
sophia-labs

mcp-context-monitor

by sophia-labs
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

mcp-context-monitor

Context window usage estimation for AI coding agents via MCP.

Parses your session transcript to estimate how close you are to context compaction, so agents can proactively save important state before it's lost. Supports Claude Code and Codex CLI backends with auto-detection.

Why

AI coding agents accumulate context through conversation, tool calls, and file reads. When the context window fills up, compaction discards older content. Agents that know compaction is coming can write key insights to persistent storage first — memory queues, documents, knowledge graphs — instead of losing them silently.

Related MCP server: Total Recall

Features

  • Live estimation — Single MCP tool returns usage percentage, distance to compaction, and status level

  • Multi-backend — Supports Claude Code (JSONL transcripts) and Codex CLI (native token counts) with auto-detection

  • Incremental scanning — Sidecar cache tracks scan position; subsequent calls only process new bytes

  • Compaction-aware — Finds the last compaction boundary and measures only post-compaction content

  • Configurable — TOML config for thresholds, token ratios, and backend-specific settings

  • Zero infrastructure — Reads the transcript file directly, no daemon or network calls

Quick Start

Requires Python 3.11+ and uv.

git clone https://github.com/sophia-labs/mcp-context-monitor.git
cd mcp-context-monitor
uv sync

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "context-monitor": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-context-monitor", "python", "server.py"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.context-monitor]
command = "uv"
args = ["run", "--directory", "/path/to/mcp-context-monitor", "python", "server.py"]

The backend is auto-detected based on which CLI has the most recent transcript.

Usage

Call context_status() from your agent:

{
  "status": "HIGH",
  "usage_percent": 73.9,
  "compaction_percent": 88.5,
  "estimated_tokens_used": 147780,
  "estimated_tokens_remaining": 19220
}

Status Levels

Status

Compaction %

Recommended Action

OK

< 50%

Normal operation

MODERATE

50–75%

Be aware, no action needed

HIGH

75–90%

Start saving important state to persistent storage

CRITICAL

90%+

Save everything immediately — compaction is imminent

How Agents Should Use This

  • Call context_status() periodically during long sessions

  • At HIGH: write key insights to memory queue, sing if at a phase transition

  • At CRITICAL: write everything important to persistent storage immediately

  • The compaction_percent measures distance to the compaction trigger, not the total window

Configuration

Create ~/.config/context-monitor/config.toml:

# Backend selection: "auto", "claude-code", or "codex-cli"
[backend]
type = "auto"

# Claude Code settings
[claude-code]
context_window = 200000
autocompact_buffer = 33000
static_overhead = 43500
bytes_per_token = 3.2
# transcript_dir = "~/.claude/projects"

# Codex CLI settings
[codex-cli]
context_window = 400000
max_output_tokens = 128000
autocompact_ratio = 0.95
static_overhead = 30000
bytes_per_token = 3.2
# transcript_dir = "~/.codex/sessions"

Environment Variables

Variable

Description

CONTEXT_MONITOR_BACKEND

Force backend: claude-code or codex-cli

CONTEXT_MONITOR_WINDOW

Context window size (tokens)

CONTEXT_MONITOR_BUFFER

Autocompact buffer (tokens)

CONTEXT_MONITOR_OVERHEAD

Static overhead estimate (tokens)

CONTEXT_MONITOR_BPT

Bytes-per-token ratio

CONTEXT_MONITOR_TRANSCRIPT

Explicit transcript file path

CONTEXT_MONITOR_PROJECT_DIR

Transcript directory

How It Works

  1. Startup: Auto-detects backend (Claude Code or Codex CLI) and finds the active session transcript

  2. Compaction detection: Scans for compaction markers to find the boundary of current context

  3. Content estimation: Parses post-compaction content, categorizing by type (text, tool calls, tool results, thinking, system)

  4. Token estimation:

    • Claude Code: Estimates tokens from byte counts using a calibrated bytes-per-token ratio

    • Codex CLI: Uses native token counts from turn_complete events when available

  5. Caching: Stores scan position in a sidecar file so subsequent calls only process new bytes

What's Counted

  • User messages, assistant messages, system prompts

  • Tool use (function calls) and tool results

  • Compaction summaries (from prior compactions)

What's Excluded

  • Thinking/reasoning blocks (not retained in context after generation)

  • JSON wrapper overhead (only content bytes are counted)

License

MIT — see LICENSE.

Available Tools

1 tool
context_statusA

Estimate current context window usage and distance to compaction. Returns phase (open/midstream/narrowing/threshold), token estimates, and profile range (coding/balanced/reading). Use this to self-manage: open (<50%), midstream (50-80%), narrowing (80-92%, start choosing what to carry), threshold (>92%, write what matters now). Optionally pass transcript_path to target a specific session file.

ParametersJSON Schema
NameRequiredDescriptionDefault
transcript_pathNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It details what the tool returns, explains the meaning of the phase thresholds, and implies behavior when transcript_path is omitted (defaults to current session). This provides robust transparency beyond the minimal expectations, with no contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loading the core purpose in the first sentence, followed by return details and usage guidance. It contains no fluff, and each sentence contributes valuable information, making it efficiently structured for quick comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's moderate complexity with one optional parameter and no output schema, the description is complete. It explains expected return values, provides self-management context, and describes parameter behavior, ensuring an agent has sufficient information to select and invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only type and default for transcript_path, with 0% description coverage. The description compensates well by stating it is optional and used 'to target a specific session file,' which clarifies the parameter's purpose and behavior. Minor gaps remain about the exact format or consequences of omission, but the description adds substantial meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('Estimate current context window usage and distance to compaction') and describes the key outputs (phase, token estimates, profile range). It is specific and unambiguous, distinguishing itself from any potential related tools even without sibling context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly explains when to use the tool ('Use this to self-manage') and provides actionable thresholds for each phase (open, midstream, narrowing, threshold) with corresponding actions. It also clarifies the optional parameter usage, making it clear when and how to invoke it appropriately.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 1 tool updatev0.1.0
    • First observedcontext_status
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.6/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool, there is no ambiguity or overlap in the set. The tool's purpose is clearly defined and distinct.

Naming Consistency5/5

The tool name 'context_status' is descriptive and follows a consistent style. Since there is only one tool, naming consistency is perfect.

Tool Count2/5

The server has exactly one tool, which is considered too few for a functional toolset. It provides a single point of functionality but lacks supporting tools.

Completeness4/5

The tool covers the core need of monitoring context usage with clear thresholds, but it lacks additional features like history tracking or configuration, leaving minor gaps.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers