DEV Community

Siftwright
Siftwright

Posted on

How many tokens do your MCP tools cost? Measure any remote MCP server in ~60 lines of Python

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

  1. initialize, then notifications/initialized, over HTTPS POST (Streamable HTTP transport).
  2. Keeps the Mcp-Session-Id header if the server issues one; stateless servers just don't send it.
  3. Handles both reply styles: plain JSON and text/event-stream (SSE data: lines).
  4. Calls tools/list, following nextCursor until the list ends.
  5. 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)}")
Enter fullscreen mode Exit fullscreen mode

Run it with any remote MCP URL:

python3 mcp_cost.py https://mcp.deepwiki.com/mcp
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 delaySec or locations makes 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 honest User-Agent fixed it.
  • Send both Accept types. Streamable HTTP servers may answer with JSON or an SSE stream; Accept: application/json, text/event-stream lets them pick.
  • Don't skip notifications/initialized. Some servers refuse tools/list on 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 the WWW-Authenticate header to find the protected-resource metadata.
  • It never calls a tool, only initialize and tools/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)

Collapse
 
sara_builds profile image
Sara •

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.

Collapse
 
robertpaschal profile image
Odinaka Robert Nnamani •

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?

Collapse
 
paul_irolla_6b5ae261d0224 profile image
Paul Irolla •

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.