Skip to content
Back to search

mcp-token-cost

What your MCP servers cost in tokens before you type a word: per server, per tool, against 46,000 measured servers, with prompt-cache checks and a CI budget.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/alexar76--mcp-token-cost/badge.svg)](/listings/alexar76--mcp-token-cost)

HTML

<a href="/listings/alexar76--mcp-token-cost"><img src="/api/listings/alexar76--mcp-token-cost/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Nothing to install: `npx mcp-token-cost`. Node 18.17 or newer. One dependency (`gpt-tokenizer`).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 172 lines
  1. # mcp-token-cost
  2. <!-- aicom-mirror-notice -->
  3. > 🔄 Synced from the [AI-Factory monorepo](https://github.com/alexar76/aicom) (append-only history). **Pull requests are welcome** — merged PRs are imported back and re-synced here. [Issues](https://github.com/alexar76/mcp-token-cost/issues) · [Pull requests](https://github.com/alexar76/mcp-token-cost/pulls)
  4. [![npm](https://img.shields.io/npm/v/mcp-token-cost?color=cb3837&logo=npm)](https://www.npmjs.com/package/mcp-token-cost)
  5. [![test](https://github.com/alexar76/mcp-token-cost/actions/workflows/test.yml/badge.svg)](https://github.com/alexar76/mcp-token-cost/actions/workflows/test.yml)
  6. [![node](https://img.shields.io/node/v/mcp-token-cost)](package.json)
  7. [![license](https://img.shields.io/badge/license-Apache--2.0%20OR%20MIT-blue)](#license)
  8. [![data](https://img.shields.io/badge/data-HISTOR%20CC%20BY%204.0-6b6b66)](https://histor.modelmarket.dev/datasets/)
  9. Every MCP server you connect sends its tool definitions to the model on every request, before you type a word.
  10. `mcp-token-cost` tells you how many tokens that is: per server, per tool, per part of a tool, against
  11. 45,922 MCP servers measured in public, with the things that quietly break your prompt cache.
  12. ```bash
  13. npx mcp-token-cost
  14. ```
  15. It reads the MCP config of Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, Gemini CLI and Codex, lists each
  16. server's tools the way your client does, and prints:
  17. ```text
  18. MCP tool definitions: 28,632 tokens on every request (o200k_base)
  19. ███····················· 14.3 % of a 200,000-token window · 5 servers, 93 tools
  20. A typical MCP server costs 1,311 tokens (median of 45,922 packages and remote hosts in HISTOR, one list each, 2026-11-16); 90th percentile 8,200.
  21. Server Tools Tokens Desc. Schemas Rank Source
  22. notion 24 17,161 504 16,379 p96 HISTOR 2026-11-20
  23. playwright 25 3,938 432 3,261 p78 HISTOR 2026-11-18
  24. github 26 3,546 287 3,001 p76 HISTOR 2026-11-18
  25. filesystem 16 2,925 1,098 1,674 p72 HISTOR 2026-11-18
  26. context7 2 1,062 541 501 p43 HISTOR 2026-11-21
  27. Rank: the share of observed MCP packages and remote hosts whose list costs less (p90 = heavier than 90 % of them).
  28. Heaviest tools
  29. 1,268 notion › API-update-page-markdown (description 67, schema 1,189) · heaviest property update_content 177
  30. 1,083 notion › API-post-search (description 17, schema 1,056) · heaviest property filter 229
  31. 876 notion › API-patch-page (description 17, schema 848) · heaviest property cover 93
  32. 806 notion › API-post-page (description 17, schema 779) · heaviest property children 62
  33. 756 notion › API-query-data-source (description 18, schema 727) · heaviest property filter_properties 47
  34. Per 1,000 requests that send this list (list prices; clients that load tools on demand send less)
  35. Claude Opus 5.5 $114.53 uncached · $5.86 cache kept warm · $143.16 cache rewritten every time
  36. Claude Sonnet 5.5 $57.26 uncached · $2.93 cache kept warm · $71.58 cache rewritten every time
  37. Claude Haiku 5.5 $2.86 uncached · – cache kept warm · $3.58 cache rewritten every time
  38. Findings (1)
  39. MED CONTEXT_SHARE (all)
  40. Tool definitions and instructions take 28,632 tokens, 14.3 % of a 200,000-token window, before the first message.
  41. ```
  42. The demo above is `--offline` on a five-server config: nothing was started, every definition came from
  43. [HISTOR](https://histor.modelmarket.dev)'s public record of that server.
  44. ## What it does that a token counter doesn't
  45. | | mcp-token-cost | a per-server counter | a web calculator |
  46. |---|---|---|---|
  47. | Your whole setup, from your client's config | ✓ (7 clients) | one server per run | pick from a catalogue |
  48. | Per tool, split into name / description / input schema / structure, heaviest schema property | ✓ | per tool, desc/schema | per tool |
  49. | Where you stand among 45,922 measured servers | ✓ percentile per server | – | catalogue max/median |
  50. | Prompt-cache breakers: order or content that changes between two reads, dates, UUIDs | ✓ | – | – |
  51. | Waste: repeated sentences across tools, huge enums, deep schemas, duplicate tool names across servers | ✓ sized in tokens | – | – |
  52. | Without running anything (`--offline`, from HISTOR's stored definitions) | ✓ | – | ✓ |
  53. | Claude's own count, including its tool-use prompt (`--claude`) | ✓ | ✓ | – |
  54. | CI: baseline, each measure checked on its own, noise floor, budget, job summary, GitHub Action | ✓ | baseline + threshold | – |
  55. | Reports: text, JSON, Markdown, self-contained HTML, SARIF | ✓ | text, JSON | page |
  56. | Price per 1,000 requests: uncached, cache kept warm, cache rewritten | ✓ | – | – |
  57. ## Install
  58. Nothing to install: `npx mcp-token-cost`. Node 18.17 or newer. One dependency (`gpt-tokenizer`).
  59. ## Usage
  60. ```bash
  61. npx mcp-token-cost # every server in your client configs
  62. npx mcp-token-cost --offline # same, but start nothing: definitions from HISTOR
  63. npx mcp-token-cost --stdio "npx -y @playwright/mcp" # one server you start
  64. npx mcp-token-cost --url https://mcp.example.com/mcp --header "Authorization: Bearer $TOKEN"
  65. npx mcp-token-cost --tools tools.json # a saved tools/list answer
  66. npx mcp-token-cost lookup npm:@playwright/mcp # HISTOR's record and how each release changed the cost
  67. npx mcp-token-cost --format html # writes mcp-token-cost.html
  68. ```
  69. `--config FILE` (repeatable) reads a specific config; `--only` / `--skip` pick servers. A server that cannot be
  70. started falls back to HISTOR's record when it is a public npm/PyPI package or a URL (say `--no-histor` to turn that
  71. off); the report says which source each row came from.
  72. ### Claude's count
  73. The default tokenizer is `o200k_base`, offline and exact for the GPT-4o family. For Claude it is an estimate:
  74. Claude's tokenizer produces roughly 15-20 % more tokens on typical text. `--claude` asks Anthropic's free token
  75. counting API for Claude's own number. It counts each server's request with and without its tools, so the figure
  76. includes the system prompt Claude adds whenever a request carries tools. It sends your tool definitions to
  77. Anthropic, and needs the SDK and a key or an `ant auth login`:
  78. ```bash
  79. npx -p @anthropic-ai/sdk -p mcp-token-cost mcp-token-cost --claude [--claude-model claude-sonnet-5-5]
  80. ```
  81. ## In CI
  82. Commit a baseline once, then check every change. Each measure (the total, the descriptions, the input schemas) is
  83. checked on its own, so a schema that doubles fails even when shorter descriptions hide it in the total. Growth under
  84. 50 tokens never fails.
  85. ```bash
  86. npx mcp-token-cost snapshot --stdio "node dist/index.js" -o mcp-tokens.json
  87. npx mcp-token-cost check --baseline mcp-tokens.json --stdio "node dist/index.js" --max-increase 10% [--budget 8000] [--update]
  88. ```
  89. GitHub Actions (the table lands in the job summary):
  90. ```yaml
  91. - uses: alexar76/mcp-token-cost@v0.1.0
  92. with:
  93. stdio: node dist/index.js
  94. baseline: mcp-tokens.json
  95. max-increase: 10%
  96. ```
  97. `--fail-on high|medium|low` fails a scan on findings, and `--format sarif` feeds code scanning.
  98. ## Findings
  99. | Code | What it means |
  100. |---|---|
  101. | `LIST_ORDER_UNSTABLE` | Two `tools/list` reads in one session returned the same tools in another order. Tools come first in the prompt, so each new order is a full prompt-cache write. |
  102. | `LIST_CONTENT_UNSTABLE` | Two reads returned different definitions: every refetch rewrites the cache from the tools onward. |
  103. | `VOLATILE_TEXT` | A date, timestamp, UUID or session id inside a definition: it changes, and the cache with it. |
  104. | `CONTEXT_SHARE` | The whole setup takes more than 10 % of the context window before the first message. |
  105. | `DUPLICATE_TOOL_NAME` | Two servers offer a tool with the same name. |
  106. | `REPEATED_TEXT` | The same sentence in three or more descriptions of one server: once in the server's instructions is enough. |
  107. | `LARGE_ENUM` | An enum with more than 40 values. |
  108. | `LONG_DESCRIPTION`, `LARGE_SCHEMA` | Over 500 / 1,500 tokens. |
  109. | `DEEP_SCHEMA` | More than 5 levels of properties and items. |
  110. Each sized finding says how many tokens per request fixing it would save.
  111. ## How it counts
  112. Exactly the way [HISTOR](https://histor.modelmarket.dev) counts, so a local number, a HISTOR record and the
  113. population curve agree to the token (checked in the test suite against HISTOR's Python reference): each tool is
  114. sent as `{"name", "description", "input_schema"}` in compact JSON, a list costs the sum of its tools, and each part
  115. is the JSON value as written. Server `instructions`, which clients put in the system prompt, are counted on their
  116. own line.
  117. The population curve (`data/distribution.json`) comes from HISTOR's weekly snapshot of 2026-11-16 (CC BY 4.0),
  118. rebuilt with `tools/build_distribution.py`: every listed server with a current tool list, 53,399 of them (27,440 npm
  119. and PyPI packages run in a sandbox, 25,959 remote endpoints). The rank counts one list per owner, each package and
  120. each remote host (its heaviest list), 45,922 in all, so a publisher that serves near-identical lists on thousands of
  121. endpoints weighs as one. Over those: median 1,311 tokens and 8 tools, 90th percentile 8,200 tokens, 99th 43,549,
  122. largest 699,910.
  123. ## What it does not tell you
  124. - **What your client actually sends.** Some clients load tools on demand or drop fields; this counts the full list.
  125. - **The provider's own wrapping**, except with `--claude`.
  126. - **Prices change.** The money table uses list prices in `data/prices.json` (dated); pass `--price` for yours.
  127. - **Which servers are good.** The rank is a token count, not a quality score.
  128. ## Privacy
  129. A scan starts your configured servers on your machine (as your client would) and talks to nothing else, except:
  130. `--offline` and the fallback ask HISTOR for public records by package name or URL; `--claude` sends tool definitions
  131. to Anthropic. No telemetry.
  132. ## License
  133. Apache-2.0 OR MIT. The bundled distribution is derived from HISTOR snapshots (CC BY 4.0).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.