Every tool an MCP server exposes is shipped to the model as JSON: name, description and input schema. Most clients load the whole tools/list result at the start of each conversation, so a big or wordy catalogue quietly eats context before the user has typed anything.
That cost is easy to measure from outside. This post is a ~60-line, stdlib-only Python script that connects to a remote MCP server the way a client does, lists its tools and estimates what they cost in tokens. It also flags tools and parameters with no description, which hurt tool selection more than they hurt the token budget.
What the script does
-
initialize, thennotifications/initialized, over HTTPS POST (Streamable HTTP transport). - Keeps the
Mcp-Session-Idheader if the server issues one; stateless servers just don't send it. - Handles both reply styles: plain JSON and
text/event-stream(SSEdata:lines). - Calls
tools/list, followingnextCursoruntil the list ends. - Estimates tokens at ~4 characters of compact JSON per token, per tool, and prints the five most expensive.
import json, sys, urllib.request
def rpc(url, method, params, req_id, session=None):
body = {"jsonrpc": "2.0", "method": method, "params": params}
if req_id is not None:
body["id"] = req_id
headers = {"Content-Type": "application/json",
"Accept": "application/json, text/event-stream",
"MCP-Protocol-Version": "2025-11-25",
"User-Agent": "mcp-cost/1"} # default Python UA is often blocked
if session:
headers["Mcp-Session-Id"] = session
req = urllib.request.Request(url, json.dumps(body).encode(), headers)
with urllib.request.urlopen(req, timeout=20) as r:
sid = r.headers.get("Mcp-Session-Id") or session
raw = r.read().decode()
if req_id is None:
return None, sid
if "text/event-stream" in r.headers.get("Content-Type", ""):
# take the JSON-RPC reply out of the SSE "data:" lines
for line in raw.splitlines():
if line.startswith("data:"):
msg = json.loads(line[5:])
if msg.get("id") == req_id:
return msg, sid
raise RuntimeError("no reply in event stream")
return json.loads(raw), sid
def tools_of(url):
init, sid = rpc(url, "initialize", {
"protocolVersion": "2025-11-25", "capabilities": {},
"clientInfo": {"name": "mcp-cost", "version": "1"}}, 1)
rpc(url, "notifications/initialized", {}, None, sid)
tools, cursor, n = [], None, 2
while True:
reply, sid = rpc(url, "tools/list", {"cursor": cursor} if cursor else {}, n, sid)
tools += reply["result"]["tools"]
cursor = reply["result"].get("nextCursor")
n += 1
if not cursor:
return init["result"].get("serverInfo", {}), tools
def tokens(obj):
# rough: ~4 characters of compact JSON per token
return round(len(json.dumps(obj, separators=(",", ":"))) / 4)
url = sys.argv[1]
info, tools = tools_of(url)
rows = sorted(((tokens(t), t["name"]) for t in tools), reverse=True)
total = sum(r[0] for r in rows)
print(f"{info.get('name')} {info.get('version', '')}: {len(tools)} tools, ~{total} tokens")
for tok, name in rows[:5]:
print(f" {tok:>6} {name}")
for t in tools:
props = (t.get("inputSchema") or {}).get("properties", {})
bare = [p for p, s in props.items() if not s.get("description")]
if len(t.get("description", "")) < 20:
print(f" ! {t['name']}: description missing or very short")
if bare:
print(f" ! {t['name']}: params without description: {', '.join(bare)}")
Run it with any remote MCP URL:
python3 mcp_cost.py https://mcp.deepwiki.com/mcp
Real output from five public servers
These are the actual results from runs on 2026-11-21 (tokens are the rough 4-chars estimate, not a tokenizer count):
DeepWiki 4.0.2: 3 tools, ~426 tokens
178 ask_wiki_question
126 read_wiki_structure
122 read_wiki_contents
docs-ai-search 0.5.0: 2 tools, ~433 tokens (docs.mcp.cloudflare.com/mcp)
358 search_cloudflare_documentation
75 migrate_pages_to_workers_guide
! search_cloudflare_documentation: params without description: query
GitMCP 1.1.0: 5 tools, ~718 tokens (gitmcp.io/docs)
Context7 4.7.3: 2 tools, ~1306 tokens
760 resolve-library-id
546 query-docs
siftwright 1.0.0: 9 tools, ~2004 tokens (our own server)
312 ats_jobs
302 youtube_transcript
! website_screenshot: params without description: pdfPageFormat, delaySec
! app_store_reviews: params without description: sortBy, minRating, maxRating
! ats_jobs: params without description: titleKeywords, excludeTitleKeywords, locations, departments, remoteOnly
Two things stand out:
- Token cost is about description length, not tool count. Context7 has two tools and costs more than GitMCP's five, because its descriptions carry detailed usage guidance. That can be a good trade: a longer description that stops the model from calling the tool wrongly is worth a few hundred tokens.
-
Missing parameter descriptions are common, including on our own server (we'll fix ours). A parameter called
delaySecorlocationsmakes the model guess the unit or format. One short sentence per parameter costs a handful of tokens and saves failed calls.
Gotchas found while writing this
-
The default Python user agent gets 403s. Three of the five servers sit behind bot protection that rejects
Python-urllib/3.x. Setting any honestUser-Agentfixed it. -
Send both Accept types. Streamable HTTP servers may answer with JSON or an SSE stream;
Accept: application/json, text/event-streamlets them pick. -
Don't skip
notifications/initialized. Some servers refusetools/liston a session that never finished the handshake. - The 4-chars rule is rough. Real tokenizers differ, and clients wrap tool definitions in their own framing. Use the number to compare servers and spot outliers, not as an exact budget. Different checkers also count slightly differently (for example, schema-only vs. the whole tool object).
Limits
- Remote servers only (Streamable HTTP). A local stdio server needs a subprocess transport instead.
- Servers that require OAuth answer
401; the script stops there. Read theWWW-Authenticateheader to find the protected-resource metadata. - It never calls a tool, only
initializeandtools/list.
Without code
If you just want the answer for one server, the free MCP server checker runs the same handshake from a browser and also reports protocol version, session model, CORS, the auth challenge and tool annotations. No signup.
If you're building agents that need web data (YouTube transcripts, screenshots, Google News, contact details, tech stacks, job listings), our hosted MCP server is at https://siftwright.com/mcp; setup docs here.
Top comments (3)
I’d validate the rough estimate against the target model’s tokenizer for the largest few tool schemas, then track tool-selection errors alongside token cost. That would make the trade-off between concise definitions and clearer guidance measurable.
Undocumented parameters are the cost nobody budgets for. did the servers with the most missing descriptions also run the highest token counts, or were those two things unrelated?
Measuring the list is the easy half. What drives the cost is how often that list is sent, so count the model calls in a session alongside the tokens each tool adds.