Skip to content

mcp.md

Latest commit

 

History

History
85 lines (57 loc) · 4.39 KB

mcp.md

File metadata and controls

85 lines (57 loc) · 4.39 KB

MCP And Codex Skills

Codex Usage Tracker can be installed as a local Codex plugin and exposes MCP tools for aggregate usage analysis.

Local Plugin

After installing the Python package, register the plugin:

codex-usage-tracker install-plugin

For a source checkout:

codex-usage-tracker install-plugin --python .venv/bin/python

Restart Codex after registration so it can discover the plugin.

Marketplace installs use the bundled MCP launcher at skills/codex-usage-tracker/scripts/run_mcp.py. On first MCP startup it creates a cached runtime under ~/.cache/codex-usage-tracker/mcp-runtime/ and installs the exact pinned Python package, so it does not require a .venv inside the plugin directory.

This is intentional: normal user installs come from the PyPI distribution codex-usage-tracking, and the plugin bootstrapper pins an exact reviewed package version so MCP startup does not accidentally track main.

The launcher stores the package spec used for that runtime and reinstalls when the bundled package pin changes. Set CODEX_USAGE_TRACKER_PACKAGE_SPEC to test a different package version or Git ref, or set CODEX_USAGE_TRACKER_RUNTIME_DIR to use a separate cache while debugging plugin startup.

Companion Skills

The plugin installs two companion skills. They are local instruction files that help Codex use this package; they do not create another hosted service or send usage data outside the machine.

  • codex-usage-tracker: operational setup and direct tracker work, including refresh, dashboards, CSV export, doctor checks, and MCP tools.
  • codex-usage-api: conversational usage analysis using stable aggregate JSON first.

Good prompts for the API companion skill:

Open dashboard.
Use my Codex Usage Tracker data to explain what drove usage this week.
Heaviest thread?
Thread leaderboard.
Find low-cache or high-context calls from today and suggest what to inspect next.
Compare usage by project for the last 7 days.
Show me what is estimated or unpriced before I trust the cost numbers.

The API skill should refresh the local index, call aggregate tools such as usage_summary, usage_query, session_usage, usage_recommendations, most_expensive_usage_calls, or usage_pricing_coverage, then explain the answer with the data scope and estimate caveats.

If MCP tools are not available, the same questions can be answered through CLI JSON commands documented in CLI And MCP JSON Schemas.

The companion skill cannot read your logged-in Codex account plan, native remaining allowance, or usage from other agentic surfaces. Remaining allowance context is only as accurate as the values you manually copy into ~/.codex-usage-tracker/allowance.json.

Tools

  • refresh_usage_index
  • usage_doctor
  • usage_summary
  • usage_query
  • usage_recommendations
  • session_usage
  • usage_call_context
  • most_expensive_usage_calls
  • usage_pricing_coverage
  • generate_usage_dashboard
  • export_usage_csv
  • init_usage_pricing_config
  • update_usage_pricing_config
  • init_usage_allowance_config

usage_doctor, usage_summary, usage_recommendations, session_usage, most_expensive_usage_calls, and usage_pricing_coverage accept response_format="json" when an agent needs stable structured output instead of markdown.

refresh_usage_index, usage_query, generate_usage_dashboard, export_usage_csv, and config-writing MCP tools return JSON dictionaries directly.

refresh_usage_index(include_archived=True) and generate_usage_dashboard(include_archived=True) are explicit all-history opt-ins. The default dashboard view excludes archived session rows so older work does not inflate the current usage picture.

Raw Context Guard

usage_call_context is disabled by default in MCP server processes. To enable it explicitly:

CODEX_USAGE_TRACKER_ALLOW_RAW_CONTEXT=1

Normal aggregate tools do not need this variable. Keep raw context disabled unless the user specifically asks to inspect local log context.

When raw context is enabled, usage_call_context accepts max_entries, max_chars, include_tool_output, and include_compaction_history. Use 0 for either limit only when the user explicitly asks for all matching entries or no character cap for that local context request. Compacted replacement history is transcript-like content; request it only for a specific call investigation, and keep the aggregate tools as the default path.