mcpcost

Measure every server in a config file

measure_config

Read-onlyIdempotent

Calculates the context-token cost of every MCP server in a config file, probing local and remote servers and reporting per-server and total usage, including failure statuses.

Instructions

Measures every server in one MCP config file (.mcp.json, Claude Desktop, Cursor, VS Code or Windsurf format): starts each local server the way the client would and stops it after tools/list, connects to each remote one, and reports the tokens per server and the total. Use it to see what a whole config costs the context window; use measure_server for one server. A server that fails to start or needs credentials is reported with its status, never thrown. Up to about 15 s per server.

Input Schema

Name	Required	Description
`path`	Yes	Path to the config file, absolute or relative to the working directory
`window`	No	Context window in tokens for shareOfWindow; default 200000 (Claude)
`noStdio`	No	true = measure the remote servers only and start no local process; default false

Output Schema

Name	Required	Description
`path`	No	The config file that was read
`total`	No	Over the servers that answered: how many, their tokens (exact when a Claude count exists, else the estimate) and the share of the window
`servers`	No	One entry per configured server: name, kind (remote or stdio) and the same fields as measure_server; or name and skipped, with the reason

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv0.3.4Oct 24, 2026

changedInput schema / properties / noStdio / description

Previous value: -"Measure remote servers only, do not start local ones"New value: +"true = measure the remote servers only and start no local process; default false"

changedInput schema / properties / path / description

Previous value: -"Path to the config file"New value: +"Path to the config file, absolute or relative to the working directory"

addedInput schema / properties / window / description

Added value: +"Context window in tokens for shareOfWindow; default 200000 (Claude)"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "path": {
+      "description": "The config file that was read",
+      "type": "string"
+    },
+    "servers": {
+      "description": "One entry per configured server: name, kind (remote or stdio) and the same fields as measure_server; or name and skipped, with the reason",
+      "items": {
+        "properties": {
+          "claudeError": {
+            "description": "Why the Anthropic endpoint refused to count, for example a schema it does not accept",
+            "type": "string"
+          },
+          "claudeTokens": {
+            "description": "Exact count from the Anthropic count_tokens endpoint, names as published; only with ANTHROPIC_API_KEY",
+            "type": "integer"
+          },
+          "claudeTokensClaudeCode": {
+            "description": "The same with the Claude Code prefix mcp__<server>__ on each tool name",
+            "type": "integer"
+          },
+          "error": {
+            "description": "The first line of the failure, when status is not ok",
+            "type": "string"
+          },
+          "kind": {
+            "enum": [
+              "remote",
+              "stdio"
+            ],
+            "type": "string"
+          },
+          "latencyMs": {
+            "description": "initialize and toolsList, milliseconds",
+            "type": "object"
+          },
+          "name": {
+            "type": "string"
+          },
+          "protocolVersion": {
+            "description": "The MCP protocol version the server negotiated",
+            "type": "string"
+          },
+          "serverInfo": {
+            "description": "name, version and title the server reports in initialize",
+            "type": "object"
+          },
+          "shareOfWindow": {
+            "description": "Percent of the context window the tool definitions take, exact when claudeTokens is present, else the estimate",
+            "type": "number"
+          },
+          "skipped": {
+            "description": "Why the server was not measured: disabled in config, or a local server under noStdio",
+            "type": "string"
+          },
+          "status": {
+            "description": "ok (answered initialize and tools/list), auth (needs credentials), payment (402), not_found, protocol_error (not MCP), timeout, dns, tls, refused, server_error, rate_limited, newer_protocol, or for a local command: install_failed, no_bin, needs_env, needs_args, needs_network, crashed",
+            "type": "string"
+          },
+          "toolCount": {
+            "description": "How many tools tools/list returned",
+            "type": "integer"
+          },
+          "toolsTokensEstimate": {
+            "description": "o200k_base tokens over the compact JSON of every tool definition; the exact Claude count is about 1.9 times this at the median",
+            "type": "integer"
+          },
+          "topTools": {
+            "description": "The ten most expensive tools: name and o200k_base tokens",
+            "items": {
+              "properties": {
+                "name": {
+                  "type": "string"
+                },
+                "tokens": {
+                  "type": "integer"
+                }
+              },
+              "type": "object"
+            },
+            "type": "array"
+          }
+        },
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "total": {
+      "description": "Over the servers that answered: how many, their tokens (exact when a Claude count exists, else the estimate) and the share of the window",
+      "properties": {
+        "servers": {
+          "type": "integer"
+        },
+        "shareOfWindow": {
+          "type": "number"
+        },
+        "tokens": {
+          "type": "integer"
+        }
+      },
+      "type": "object"
+    }
+  },
+  "type": "object"
+}

First observedv0.1.0Oct 15, 2026

TDQS

A4.7/5.0

Behavior5/5

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

Annotations only declare the safe, idempotent, open-world profile; the description goes further by disclosing that local servers are actually spawned and stopped after tools/list, that remotes are connected to, that failures and credential-required servers are reported as status rather than thrown, and a ~15 s per-server ceiling. These are exactly the side-effect and latency facts an agent needs before invoking a process-launching tool.

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?

Three sentences, front-loaded with what it does, then the routing hint, then failure/timeout semantics. The parenthetical client-format list is compact and functionally necessary; nothing is padded.

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?

For a multi-parameter tool with a full output schema and strong annotations, the description covers scope, execution model, error behavior, and timing. Nothing an agent needs to call it correctly is missing.

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

Parameters3/5

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

Schema description coverage is 100%, so path, window, and noStdio are already fully documented in the schema. The description implies process-spawning behavior ('starts each local server') that relates loosely to noStdio, but adds no syntax or format detail beyond what the schema provides. Baseline 3 is correct here.

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?

States a specific verb ('measures') and resource ('every server in one MCP config file'), enumerates supported file formats, and explicitly contrasts with the sibling measure_server for single-server measurement. An agent can distinguish it from all four siblings without opening a schema.

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?

'Use it to see what a whole config costs the context window; use measure_server for one server' gives both the when and the named alternative with the condition that selects it. No inference required.

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

Deploy Server