mcpcost

mcpcost

[CI] [npm mcpcost] [license] [Glama]

Is that MCP server alive, and what does it cost your context window?

Live board: mcpcost.ulehla.dev

mcpcost probes every remote server in the official MCP registry and records, for each one:

• whether it answers initialize and tools/list, and how fast
• the protocol version it negotiates
• whether it needs auth, which scheme (from WWW-Authenticate), and how a client gets in: OAuth with dynamic client registration, OAuth with a client id from the publisher, or a key, read from the server's public OAuth metadata
• whether it asks for payment (HTTP 402)
• how many tools it has and how many tokens their definitions cost

mcpcost: what do your own servers cost?

npx mcpcost                     # reads Claude Code, Claude Desktop, Cursor, VS Code, Windsurf and Gemini CLI configsnpx mcpcost --config .mcp.json  # one filenpx mcpcost --budget 30000      # exit 1 when the total is above the budget, for CInpx mcpcost --claude            # exact counts from the Anthropic count_tokens endpoint (free, needs ANTHROPIC_API_KEY)npx mcpcost mcp                 # the same measurements as an MCP server over stdio, for your agent

It starts every configured server the way your client does, lists the tools and prints the token cost per server and in total. See packages/mcpcost.

Servers that need auth

A server that answers 401 is reachable but not measured until it gets credentials. Store them once; every later measurement of that URL uses them.

npx mcpcost auth https://mcp.linear.app/mcp                                   # OAuth: register, consent in the browser, store the tokensnpx mcpcost auth https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer ghp_…"   # an API key insteadnpx mcpcost auth --list                                                       # what is stored, without the secrets

The OAuth flow follows the MCP authorization spec: discovery, dynamic client registration, PKCE, a callback on 127.0.0.1. The consent screen is the one step that needs a person. After it, the tokens live in ~/.mcpcost/credentials.json (mode 0600, or $MCPCOST_CREDENTIALS), npx mcpcost sends them for that URL, and a refreshed token goes back to the file.

The board does the same: npm run credentials:push copies the file into the D1 table credentials; the daily run reads it before the probe, writes the refreshed tokens back after it, and marks the server "measured with credentials". A refresh token that a service revokes or lets expire needs the consent step again.

Without credentials, the board still shows a tool set for many gated servers: tool definitions do not depend on the token, so when the publisher's repository holds a package on npm or PyPI, probe/derive-packages.ts finds it and the weekly container run measures it with placeholder values. The server page then says "from the publisher's package". probe/derived-aliases.json maps the few servers whose registry entry names no repository.

In CI, as a GitHub Action

[GitHub Marketplace]

- uses: ondraulehla/mcpcost@v1  with:    config: .mcp.json   # one or more config files, one per line    budget: 30000       # fail when the tool definitions cost more than this

The job summary gets a table with every server, its result and its cost, plus the most expensive tools. A pull request that adds a 40 000-token server fails the check. Set claude: true and put ANTHROPIC_API_KEY in env for exact counts from the free count_tokens endpoint; the default is the o200k_base estimate. Outputs: tokens, servers, over-budget.

On a pull request the action also measures the same config files on the base branch and posts one comment with the difference: servers added, removed and changed, the token delta per server, the new total and the budget verdict. The comment is updated on every push, never duplicated. The job needs pull-requests: write for it; without that permission the step warns and the check still runs. Set comment: false to turn it off. A complete workflow is in .github/examples/mcp-budget.yml.

In Claude Code, as a plugin

In a Claude Code session:

/plugin install mcpcost --marketplace ondraulehla/mcpcost

Or from the shell: claude plugin marketplace add ondraulehla/mcpcost, then claude plugin install mcpcost@mcpcost.

The plugin adds one skill, /mcpcost:measure, which runs npx mcpcost on your configs and reads the result, and the board's MCP server, so Claude can look up or probe a server before it goes into a config. What the plugin itself costs: one skill description in the context, and four tools that Claude Code defers behind tool search.

The board

mcpcost.ulehla.dev is rendered on the edge from a D1 database and refreshes every night. The only scripts it loads are a theme switch and the Cloudflare Web Analytics beacon, which counts page views without cookies.

• Overview: the share of servers that answer, token cost percentiles, and a form to check any server
• Check: probes one URL live, with the same steps as the daily run; the exact token count runs in the browser
• Statistics: results by cause, token cost and tool count percentiles, the heaviest tool sets, protocol versions, auth schemes, transports, biggest publishers
• Servers: full-text search over name, title, description and host (word prefixes, so git copilot finds the GitHub Copilot servers), filters by result, protocol and transport, seven sorts, and every filter is a plain URL you can share
• Server page: status, latency, protocol, capabilities, the most expensive tools, servers with the same tool set, history, the badge, and e-mail alerts: a mail when the server stops answering, comes back, or its tool set or token cost changes
• Compare: two to five servers side by side, status, access, tools, exact tokens, share of a 200k window, latency, with the cheapest and the spread; /compare?s=<name>&s=<name>, linked from every server page
• Track: a server that is not in the registry can be tracked from the check page; the daily probe then measures it under the name url/<host>/<path>
• Hosts: the 500 biggest publishers with how many distinct tool sets they actually serve
• Report: one page a month, The state of the MCP registry, read from the daily runs, with a CC BY 4.0 dataset of every server

For agents and scripts

• JSON: /api/s/<name>.json, /api/lookup.json?url=… (the board's row for an endpoint URL, no probe), /api/servers.json?q=…&status=ok&sort=tokens, /api/check.json?url=…, /api/summary.json. The list API takes at most 6 requests in 10 seconds from one address; its answers are cached for three hours.
• Re-check evidence for the registry, the newest run: /data/mcpcost-evidence-latest.json.gz (the row shape of modelcontextprotocol/registry#1715, changes after each daily run), with its index /data/mcpcost-evidence-latest.index.json.
• MCP server over Streamable HTTP, no auth: https://mcpcost.ulehla.dev/mcp with the tools lookup_server, search_servers, compare_servers, check_server, registry_summary. The manifest for the registry is site/server.json.
• /llms.txt lists all of it. /tokens answers the general question: how many context tokens does an MCP server cost.

Each server on the board gets a page and a badge:

[![mcpcost](https://mcpcost.ulehla.dev/badge/io.github.you/your-server.svg)](https://mcpcost.ulehla.dev/s/io.github.you/your-server)

First full run, 2026-10-03

The registry held 38 942 latest entries. 24 294 of them have a remote endpoint, and the probe connected to all of them in 40 minutes.

Of the 12 975 servers that answered:

• the median tool set costs 1 727 tokens, the 90th percentile 7 429, the 99th 28 200
• 208 servers cost more than 20 000 tokens, 46 more than 50 000, and 3 more than a whole 200k window
• the heaviest is com.replynodes/mcp: 66 tools, 431 925 tokens
• the median server has 8 tools, the largest 1 385
• median initialize latency is 455 ms, the 90th percentile 1.5 s
• 60 % negotiate protocol 2025-11-25, 24 % still 2025-03-26, 4 % 2024-11-05
• 122 servers answer with protocol 2026-07-28, which the current TypeScript SDK rejects

The registry is lumpy. 16 161 of 16 534 hosts publish one server. Five hosts publish more than 6 000 entries between them: one Workers subdomain with 2 365 near-identical entries, a gateway with 1 716 entries of which 1 321 return a JSON-RPC error on initialize, and a host with 276 entries that all answer 402.

The monthly report and the dataset

/report/2026-10 is The state of the MCP registry, October 2026: the registry in numbers, what changed between the first full run and the run of 2026-10-24, token cost, auth, the lumps, protocol versions, what the registry does not catch, and the method in six sentences. The page reads only the runs table (the runs of the month up to the run day, one query) and is cached for a day, so it costs nothing on the free tier. /report lists the months; site/src/lib/reports.ts has one entry per report with the day of the run it is pinned to. The dataset that goes with it, data/mcpcost-2026-10.json.gz on the site, has one row per probed server: name, host, transport, status, HTTP status, auth scheme and kind, protocol version, tool count, the o200k estimate, the exact Claude counts and the probe time. A row's numbers are what /api/s/<name>.json gives for that server on that day. The licence is CC BY 4.0; the document carries the licence, the field list and a citation at the top. probe/dataset.ts writes data/latest/dataset.json and its gzip on every daily run (kept in the run artifact), and --publish site/public/data/mcpcost-YYYY-MM.json.gz copies the gzip into the site when it is under 10 MB: a static file is served before the Worker and costs no request. A bigger file would go out as a GitHub release asset instead. To publish a month: run the probe or download the run artifact into data/latest, run node --import tsx probe/dataset.ts --publish site/public/data/mcpcost-YYYY-MM.json.gz, add the month to reports.ts, write the page, and commit the file with it.

The same run goes out as re-check evidence for the registry, in the row shape agreed in modelcontextprotocol/registry#1715: entry, checked_at, check (endpoint or package), state (alive, auth, transient, dead, unknown) and evidence. probe/dataset.ts writes it daily next to the dataset, and the month's copy is /data/mcpcost-evidence-YYYY-MM.json.gz. The newest run is always at /data/mcpcost-evidence-latest.json.gz, with /data/mcpcost-evidence-latest.index.json next to it (run date, entries per state and per check, size, SHA-256, shape). Neither file is in git. The probe keeps the file as the artifact evidence-<run id>, and deploy.yml puts it into site/public/data before every build: after each successful probe run, and on each push, so a push does not take it off the site. probe/evidence-latest.ts refuses a file that is not whole, and the site then keeps the file it has. A deploy after a probe run builds main as it is, the same as a manual deploy, and it is its own workflow run, so it cannot fail the probe.

How it works

registry ──▶ probe/run.ts ──▶ data/raw/probe-run.json                                   │                        probe/build-data.ts                                   │               data/latest/{servers,summary,hosts}.json                                   │                           probe/to-sql.ts ──▶ import.sql ──▶ D1                                                                │                              site/ (Astro on Workers) ◀────────┘

• packages/mcpcost/ the library and the CLI mcpcost: registry client, remote and stdio probe, config discovery, token counting
• probe/ the batch runner and the data pipeline
• site/ the board: Astro 7 with the Cloudflare adapter on Workers, rendered from D1 with FTS5 search, SVG badges, no client JavaScript beyond the theme switch and the analytics beacon
• .github/workflows/probe.yml runs the whole pipeline daily: probe, counts, build-data, to-sql, the D1 import. The run's summary.json, servers.json and hosts.json go up as a workflow artifact; the next run diffs against it and imports only the rows that changed, inside the free tier's 100 000 row writes a day
• .github/workflows/deploy.yml deploys the site when site/ changes

Methodology

• Transport. The probe uses the official TypeScript SDK as a client. Streamable HTTP first, SSE when that is the only remote.
• No GET stream. The probe answers 405 to the SDK's standalone GET, so it never opens a server-to-client stream. The probe needs no server-initiated messages, and some servers stall tools/list while that stream is open (DeepWiki held it for 15 s and never answered the POST meanwhile).
• Exact token count. The daily run asks the Anthropic count_tokens endpoint for every alive server, and the Gemini countTokens endpoint when GEMINI_API_KEY is set (the CLI: --gemini). Anthropic first: one request with the server's tools plus a marker tool, one with the marker tool only, and the difference is what the tools cost in claude-opus-5-5. A second count uses Claude Code's mcp__<server>__ prefix on each tool name. The endpoint is free and calls no model. A server is counted again only when its tool definitions change. About 5 % of servers publish a schema the endpoint refuses; they show the estimate and the reason.
• Estimate. Each tool is serialised as compact JSON with name, description and input_schema, and counted with the o200k_base tokenizer. The exact count is about 1.9 times the estimate at the median. The estimate needs no key and is the same for every server.
• Same tool set. A hash of the sorted tool names and schema sizes marks servers that serve identical tools under different names.
• Timeouts. 15 seconds per request. At most one probe runs against a host at a time.
• Getting access. For a server that answers 401 or 403, the probe reads the OAuth protected-resource metadata (RFC 9728) and the first authorization server's metadata (RFC 8414, then OpenID discovery): authorization servers, scopes, the publisher's guide, dynamic client registration (RFC 7591), PKCE, grant types. The server page shows it as "Getting access", the JSON API as authKind and authMetadata. Two to four small requests, no token, no consent; the probe result does not change.
• Identification. Every request carries the User-Agent mcpcost/<version> (+https://github.com/ondraulehla/mcpcost). To exclude a server, open an issue with its registry name.

Run it

npm installnpm run probe -- --sample 200 --per-host 2        # a sample, results in data/samples/npm run probe -- --all --out data/raw/probe-run.jsonnode --import tsx probe/build-data.ts --in data/raw/probe-run.json --out data/latestnode --import tsx probe/to-sql.ts --in data/latest --out data/latest/import.sqlnpm test --workspaces --if-present

Site, locally against a local D1:

cd sitenpm run db:schema:local && npm run db:import:localnpm run dev

The MCP endpoint answers initialize, tools/list, ping and the notifications from site/src/lib/mcp-snapshot.json, without the SDK; every other request goes to the SDK. The snapshot must be the SDK's own answers, or the site build fails: after a change to a tool definition, run npm run mcp:snapshot -w site and commit the new file in the same commit. npm test -w site, which the build runs too, holds the two answers side by side, byte for byte.

A shared link shows a card: a 1200x630 PNG in site/public/og/. There is a default card, and a card each for the October report, Compare and Statistics. site/src/lib/og.ts lists the cards and their text. The layout puts the card of a page into og:image and twitter:image; a page can also give the layout an image of its own. npm run og -w site draws the cards again with satori and resvg (as WebAssembly). It runs offline, with the fonts from node_modules and the colour tokens of Layout.astro. npm test -w site fails when a committed card is not what the script draws now: after a change to a card, a font or a colour token, commit the new PNGs in the same commit. A card has no daily numbers, because they go out of date. The cards are static files, so they are served before the Worker and cost no request. To use the default card as the social preview of the GitHub repository, upload site/public/og/default.png in the repository settings, under Social preview.

The alert mails need a sending domain: either Cloudflare Email Sending (Workers Paid plan, then the send_email binding in site/wrangler.jsonc) or Resend (verify the domain there and npx wrangler secret put RESEND_API_KEY). Without one, the watch form says that the confirmation mail could not be sent.

Deploying needs a Cloudflare account with a D1 database named mcpcost (wrangler d1 create mcpcost, then put the id in site/wrangler.jsonc). The workflows expect the repository secrets CLOUDFLARE_API_TOKEN (Workers Scripts: Edit, D1: Edit) and CLOUDFLARE_ACCOUNT_ID. Both workflows apply site/schema.sql and the pending files in site/migrations/ on every run. The two indexes on the shown token count (migrations 007 and 008) are the exception: each build writes a row per server, so the probe workflow applies one a day before the import and gives the import the rest of the write budget. A new database needs them applied by hand once.

The edge rules

The Workers Free plan counts every request the Worker answers, a 403 as much as a page. On 2026-10-22 and 23 scrapers with Chrome user agents on hosting addresses (Meta's cloud, Alibaba Cloud, RapidSeedbox) made 4 000 list variants an hour and spent the account's 100 000 requests a day, although the Worker refused them. What stops them must run before the Worker: site/edge/rules.mjs writes the zone's WAF rules through the API, idempotently.

• a custom rule that blocks Meta's training crawler, meta-externalagent, on the whole host: a verified bot that ignores robots.txt, made 28 000 of the Worker's 31 000 requests in the twelve hours to 2026-10-24 05:42 UTC, and sends no readers (the link preview facebookexternalhit is not blocked)
• a custom rule that blocks those networks on the whole host, verified bots excepted
• a custom rule that gives every list variant (/servers?…) from anything but a verified bot a managed challenge; a browser passes it once, a script does not. The list API (/api/servers.json) is not in it: scripts and agents cannot pass a challenge, so the API stays open under the rate limiting rule
• a custom rule that blocks a verified bot on the list variants: robots.txt disallows them for everyone, search engines never ask, and Meta's crawler (meta-externalagent behind a Chrome agent string) walked 3 000 of them an hour on 2026-10-23
• the one rate limiting rule of the Free plan: more than six list variants in ten seconds from one address is blocked for ten seconds

CLOUDFLARE_API_TOKEN=… node site/edge/rules.mjs --dry-run   # shows what it would writeCLOUDFLARE_API_TOKEN=… node site/edge/rules.mjs

The Edge rules workflow (.github/workflows/edge.yml) runs the script when the file changes on main, or by hand, with the CLOUDFLARE_ZONE_TOKEN secret: a token with Zone: Zone WAF: Edit and Zone: Zone: Read on the zone. The probe's token has neither. The middleware in site/src/middleware.ts keeps the same refusals as a second layer, for the workers.dev host the zone rules do not see.

The watch

site/edge/watch.mjs says who read the board in a window of time and what it cost: the Worker's requests and D1 rows per hour from the account's analytics, and the networks, agents and URL shapes behind them from the Worker's logs. The Watch the edge workflow (.github/workflows/watch.yml) runs it every hour, over the time since the previous scheduled run (GitHub runs a schedule late and skips hours at times); the thresholds apply to the worst hour of that window. A threshold crossed (5 000 Worker requests an hour, 800 an hour from one network whose agents do not name a crawler, 300 list variants an hour from one network whatever it calls itself, a million D1 rows an hour; the WATCH_* variables) turns the run red and opens the issue labelled edge-watch, or adds the hour to the open one. The tables name the network; its ASN goes into SCRAPER_ASNS in site/edge/rules.mjs, and the Edge rules workflow blocks it before the Worker. The report also names the D1 queries that read the most rows in those hours. With Zone: Analytics: Read on the zone token, it shows what the zone stopped before the Worker as well.

CLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=… node site/edge/watch.mjs                                   # the last hourCLOUDFLARE_API_TOKEN=… CLOUDFLARE_ACCOUNT_ID=… node site/edge/watch.mjs 2026-10-22T22:00:00Z 2026-10-23T06:00:00Z   # one night

A run started by hand with quiet on only writes the report: a look back at a past window does not open an issue or turn red for an hour that was already reported.

gh workflow run watch.yml -f from=2026-10-24T19:00:00Z -f quiet=true

The old host

The site was mcp-pulse.ulehla.dev until 2026-10-15. The old host stays a route of the Worker, and the middleware in site/src/middleware.ts answers every request on it with a 301 to mcpcost.ulehla.dev.

Static assets are served before the Worker, and the Astro adapter serves prerendered pages before the middleware too, so a file in site/public/ or a prerendered page answers 200 on the old host. run_worker_first in wrangler.jsonc does not change that. So robots.txt, llms.txt and the methodology page are routes, and every page a crawler reads goes through the middleware. Only the favicon, the fonts under /_astro/, the social cards under /og/, the datasets under /data/ and the search engine verification file remain static.

To redirect those as well, with no Worker invocation at all, add a Redirect Rule to the ulehla.dev zone in the Cloudflare dashboard (Rules, Redirect Rules, Create rule):

• When incoming requests match: Hostname equals mcp-pulse.ulehla.dev
• Then: Dynamic redirect, expression concat("https://mcpcost.ulehla.dev", http.request.uri.path), status code 301, preserve query string on

Redirect Rules run before the Worker and before static assets, so the rule covers every path. The middleware stays as the fallback for the workers.dev host, which the zone rule does not see.

Releases

A tag v0.Y.Z starts the Release workflow (.github/workflows/release.yml). It checks that the version in the five files is the version of the tag (node scripts/version.mjs --check), runs the tests and npm run check -w site, and packs the package. Then it publishes the package to npm with provenance, publishes site/server.json to the MCP registry and makes the GitHub release. It needs no npm token, no OTP and no mcp-publisher login: npm trusts the workflow file (trusted publishing), and the registry takes the GitHub OIDC token of the run.

One time, on npmjs.com. Do it on the day of the first release: a new trusted publisher expires when it does not publish within 2 days.

1. Open the package mcpcost, then Settings. In the Trusted Publisher section, select GitHub Actions.
2. Organization or user: ondraulehla. Repository: mcpcost. Workflow filename: release.yml. Environment name: empty.
3. Under Allowed actions, allow npm publish. A trusted publisher made after 2026-09-03 allows only npm stage publish, and a staged version waits for an approval with 2FA.
4. Save. The same from the shell, with npm 11.15.0 or later and 2FA: npm trust github mcpcost --file release.yml --repo ondraulehla/mcpcost --allow-publish.

After the first release, Settings, Publishing access, "Require two-factor authentication and disallow tokens" stops all publishes with a token. The workflow continues to publish.

A release:

node scripts/version.mjs patch       # or minor, or 0.3.5: sets the version in the five filesgit commit -am "mcpcost 0.3.5: …"    # the message of this commit becomes the release notesgit push origin maingit tag v0.3.5 && git push origin v0.3.5

• To test the setup before the tag: Actions, Release, Run workflow, with the "Dry run" box selected. It runs the checks, npm publish --dry-run and the registry login, and publishes nothing. The warning "npm did not accept this workflow" means that the trusted publisher on npmjs.com does not match. The dry run does not check the allowed actions.
• An annotated tag (git tag -a v0.3.5 -m "…") gives its message as the release notes.
• When a run fails, run the failed jobs again. Each publish step skips a version that npm or the registry has already.
• A run from main without "Dry run" is a release without a tag push: the release makes the tag on that commit.
• A package release is never the Latest release (--latest=false). So the Latest release of the repository stays the release of the GitHub Action (v1.1.0), which its Marketplace page shows. The Action has its own releases, v1.x.y, published to the Marketplace from the release form on GitHub, and its tag v1 moves to the newest one. The workflow does not touch them. Only a tag v0.Y.Z starts it, so the package stays below 1.0.0 until it has a tag scheme of its own.

Licence

MIT