# Ctxtax > MCP server from HarryXin0919/ctxtax. - **Type:** MCP server - **Install:** `agentstack add mcp-harryxin0919-ctxtax` - **Verified:** Yes โ€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [HarryXin0919](https://agentstack.voostack.com/s/harryxin0919) - **Installs:** 0 - **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [HarryXin0919](https://github.com/HarryXin0919) - **Source:** https://github.com/HarryXin0919/ctxtax ## Install ```sh agentstack add mcp-harryxin0919-ctxtax ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # ๐Ÿงฎ ctxtax ### See exactly how many context tokens every MCP server and tool costs your Claude requests โ€” *before you say a word.* [](https://www.npmjs.com/package/ctxtax) [](LICENSE) [](https://nodejs.org) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io) [](https://claude.com) [](#contributing) `#mcp` ยท `#claude` ยท `#anthropic` ยท `#tokens` ยท `#context-window` ยท `#cli` ยท `#linter` **English** ยท [็ฎ€ไฝ“ไธญๆ–‡](README.zh-CN.md) ยท [็น้ซ”ไธญๆ–‡](README.zh-TW.md) ยท [ๆ—ฅๆœฌ่ชž](README.ja.md) ยท [ํ•œ๊ตญ์–ด](README.ko.md) ยท [Espaรฑol](README.es.md) ยท [Franรงais](README.fr.md) ยท [Deutsch](README.de.md) ยท [Portuguรชs](README.pt-BR.md) [Why](#why-accurate-counts-matter) ยท [How it works](#how-it-works) ยท [Install](#install) ยท [Usage](#usage) ยท [Lint](#lint-for-mcp-server-authors) ยท [Tool Search](#tool-search-modelling) ยท [CI gate](#ci-enforce-a-context-budget-on-prs) ยท [Roadmap](#roadmap) --- Every MCP tool you connect quietly injects its JSON schema into the model's context on **every** request. A handful of servers can burn 30โ€“60k tokens of "context tax" before your first prompt โ€” you pay it on each turn, and it crowds out the window you actually wanted to use. `ctxtax` connects to your MCP servers, reads their real tool definitions, and tells you what they cost โ€” per tool, per server, in tokens and in dollars. ```text github 17.6k tokens (26 tools) โ‰ˆ $0.0879/msg create_or_update_file โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1.4k create_pull_request โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 1.2k list_commits โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆ 760 ... filesystem 4.1k tokens (11 tools) โ‰ˆ $0.0205/msg ... โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ TOTAL context tax: 21.7k tokens โ‰ˆ $0.1084/msg [model: claude-opus-4-8] These tokens are sent on every request that exposes these tools (minus prompt caching). ``` ## Why accurate counts matter Most "token counter" tools reach for `tiktoken`. **That's OpenAI's tokenizer โ€” it undercounts Claude by ~15โ€“20% on normal text, and worse on JSON schemas and nonโ€‘English.** A budgeting tool that's 20% wrong is worse than no tool. `ctxtax` counts the way Claude actually counts: it calls Anthropic's official [`/v1/messages/count_tokens`](https://platform.claude.com/docs/en/build-with-claude/token-counting) endpoint (free, modelโ€‘specific). Set `ANTHROPIC_API_KEY` and you get exact numbers. No key? You still get a clearlyโ€‘labeled estimate โ€” never a number pretending to be exact. ## How it works 1. **Discover** โ€” reads your `.mcp.json` (or takes a server command directly). 2. **Connect** โ€” speaks MCP over stdio or Streamable HTTP and calls `tools/list` to get the *real* schemas, exactly as your client sends them. 3. **Count** โ€” converts each tool to the Anthropic tool shape and measures its **marginal** cost: `count_tokens(with the tool) โˆ’ count_tokens(baseline)`. 4. **Report** โ€” a sorted bar chart per server, totals, and the $/message at your chosen model's input price. ## Install ```bash npm install -g ctxtax # or: npx ctxtax export ANTHROPIC_API_KEY=sk-ant-... # optional but recommended for exact counts ``` ## Usage ```bash ctxtax # scan ./.mcp.json ctxtax -c path/to/.mcp.json # a specific config ctxtax -s github # just one server from the config ctxtax -m claude-sonnet-4-6 # count/price against another model ctxtax --json # machine-readable output ctxtax lint # token-saving tips for MCP server authors ctxtax toolsearch # model deferred (Tool Search) vs always-loaded cost ctxtax --html report.html --badge docs/context-cost.svg # shareable card + README badge ctxtax -- npx -y @modelcontextprotocol/server-filesystem /tmp # one-off server (after --) ``` ### Lint (for MCP server authors) `ctxtax lint` flags what's making your tools expensive โ€” over-long descriptions (measured exactly), bloated schemas, huge enums, redundant titles โ€” with an estimate of the tokens you'd save: ```text filesystem / search_files โœ– [long-description] description is ~121 tokens (target โ‰ค 120). Keep only what Claude needsโ€ฆ (~1 token saveable) โ€ข [verbose-tool] the whole tool is ~206 tokens โ€” among the most expensive; trim the schema or split it. โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ 27 findings ~859 tokens/msg recoverable ``` `.mcp.json` is the standard Claude Code / Claude Desktop format: ```json { "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }, "github": { "url": "https://api.githubcopilot.com/mcp/" } } } ``` ### Tool Search modelling Anthropic's [Tool Search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) defers tool definitions โ€” they load on demand instead of all upfront. `ctxtax toolsearch` estimates what you'd pay **upfront** with it on vs the always-loaded cost: ```text server always deferredโ†‘ note filesystem 4.1k 0.6k stdio โ€” deferrable github 17.6k 17.6k HTTP/Streamable โ€” not deferred today (#40314) always-loaded total: 21.7k tokens deferred upfront: 18.2k tokens (โˆ’3.5k upfront; the rest loads on demand) ``` The catch it surfaces: **stdio servers are deferrable, but HTTP/Streamable MCP servers are not deferred today** ([claude-code#40314](https://github.com/anthropics/claude-code/issues/40314)) โ€” they pay full price upfront regardless. (Estimate: deferrable servers are modelled as keeping a name + 1-line stub in the search index.) ### Shareable report & badge `--html` writes a self-contained HTML budget card (open it, share it); `--badge` writes a README badge. ```bash ctxtax --html report.html # a shareable HTML card (no external assets) ctxtax --badge docs/context-cost.svg # a static SVG badge (or .json for a shields.io endpoint) ``` Then drop it in your README: ``. ## CI: enforce a context budget on PRs `ctxtax ci` turns the budget into a check. It fails the build when your MCP context tax crosses a threshold, and posts a **diff** on the PR โ€” *"this PR adds 4 tools = +3,200 tokens/msg."* (Claude Code's `/context` is great interactively, but it can't run in CI; this can.) ```bash # locally: save a committed budget snapshot ctxtax ci --save # writes .ctxtax.json # in CI: fail if over budget, diff against the base branch's snapshot, comment on the PR ctxtax ci --max-tokens 30000 --baseline .ctxtax.base.json --comment out.md --summary ``` Drop-in GitHub Action: ```yaml # .github/workflows/ctxtax.yml name: ctxtax on: pull_request permissions: contents: read pull-requests: write jobs: budget: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: HarryXin0919/ctxtax@v0.1.0 with: max-tokens: "30000" anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }} # optional; exact counts ``` The action fetches the base branch's `.ctxtax.json`, renders the per-tool diff, posts/updates a single PR comment, writes a job summary, and fails the check if you blow the budget. ## Roadmap `scan`, `ci`, `lint`, and `toolsearch` are all shipped. Next ideas (PRs welcome): prompt-caching-aware costs, an editor extension. Have one? [Open an issue](../../issues). ## Contributing Issues and PRs welcome. `npm install`, then `npm run dev -- -- npx -y @modelcontextprotocol/server-filesystem /tmp` to try it locally. ## License [MIT](LICENSE) ยฉ Harry Xin ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source โ€” we do not rehost the code. - **Author:** [HarryXin0919](https://github.com/HarryXin0919) - **Source:** [HarryXin0919/ctxtax](https://github.com/HarryXin0919/ctxtax) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** โ€” Free ## Security capabilities Automated source analysis of v0.1.0 โ€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source โ€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** โ€” security scan: passed โ€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-harryxin0919-ctxtax - Seller: https://agentstack.voostack.com/s/harryxin0919 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack โ€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.