mcptokens

mcptokens

375 tokens in your agent's harness. One tool, inspect, thatcounts the tool-definition cost of any other MCP server (stdio orStreamable HTTP) before you enable it.

pip install mcptokens

Why

When your agent enables a new MCP server, its tools enter theagent's context on every turn. The cost compounds fast. mcptokenslets the agent ask is this server cheap enough? before flippingthe switch.

Transports

Same tool, same response shape:

• stdio (default): spawn a local process and speak JSON-RPCon its stdin/stdout.
• streamable_http: POST initialize and tools/list to aremote MCP endpoint per MCP 2025-03-26. Server may reply viaapplication/json (one message) or text/event-stream.

How

Add mcptokens to your agent's MCP config (Claude Code, Pi,OpenCode, Codex, ...). The agent gains one tool:

inspect(command=["python", "-m", "some_mcp_server"])
# stdio spawn argv, same as your MCP config

inspect(command=["hound"])
# pre-installed binary

inspect(
    transport="streamable_http",
    url="http://localhost:8080/mcp",
    headers={"Authorization": "Bearer ..."},  # optional
)
# remote MCP server

# Returns the same JSON shape every call:
# {ok, server, tool_count, wire_total_tokens,
#  tools: [{name, total}], encoding, elapsed_ms, version}

wire_total_tokens is the number to report. Use it BEFOREenabling a candidate server: a large value means don't enable.

The numbers

Install

pip install mcptokens

Add mcptokens to your agent's mcpServers / mcp_servers. Done.

CLI (debug surface)

mcptokens python -m some_mcp_server     # human table
mcptokens --json python -m some_mcp_server   # pipeline-friendly JSON
mcptokens --timeout 30 python -m srv    # custom spawn, custom timeout
mcptokens serve                         # run as an MCP server

License

MIT. pip install mcptokens from the canonical PyPI index.