MCP Usage

MCP工具表面令牌表

此存储库实现了TypeScript CLI(mcpusage)它再现了中描述的工作流程 *TypeScript中MCP工具广告的令牌成本测量*。它获取每个工具定义 从MCP服务器，序列化生成的“工具表面”，并测量阻止的令牌数量 将占用一个或多个OpenAI和Anthropic模型（从GPT-5/GPT-5.1家族开始， Codex变体和克劳德·索内特）。

特性

• 通过stdio（启动本地进程）或HTTP/SSE端点连接到任何MCP服务器。
• 自动分页 list_tools 响应，因此对整个刀具表面进行计数。
• 确定性地序列化工具元数据（按工具名称排序，可选 _meta 剥离）。
• 用途 @dqbd/tiktoken （OpenAI模型）和 @anthropic-ai/tokenizer （Claude家族）用于具有模型感知或自定义编码回退的令牌会计；Anthropic API模式报告官方计数，并包括本地标记器总数以供比较。
• 每次运行支持多个模型，并在假设标记器与正式发布标记器时突出显示。
• 打印每个工具的Claude样式细分，以便您可以看到哪些MCP模式对象最昂贵。
• 可以导出捕获的工具广告JSON以进行离线差异化或审计。

入门指南

npm install
npm run build # compiles the CLI to dist/cli.js

或者从npm（Node.js 20+）安装：

# quick, no global install
npx mcpusage --help

# or install globally
npm install -g mcpusage
mcpusage --help

为了快速迭代，您可以直接从TypeScript运行CLI：

npm run dev -- --help

构建后，通过以下方式调用二进制文件：

node dist/cli.js --help
# or install globally / link if desired:
npm link
mcpusage --help

使用示例

测量本地stdio MCP服务器

mcpusage \
  --stdio npx -y @modelcontextprotocol/server-filesystem ./sample_files \
  --model gpt-5 --model gpt-5.1-codex

使用Streamable HTTP测量远程服务器

mcpusage \
  --url https://mcp.example.com/mcp \
  --header Authorization:"Bearer " \
  --transport streamable \
  --dump-tools ./snapshots/server-a.json

通过shell脚本启动

mcpusage --stdio-shell "poetry run python ./scripts/server.py" --format json

CLI标志（摘要）

• --stdio / --stdio-shell ：通过stdio启动服务器；与...结合 --stdio-cwd, --stdio-env，以及 --stdio-echo-stderr （stdout始终保持沉默，除非您选择加入，否则stderr将被抑制）。
• --url ：通过Streamable HTTP（默认）或SSE连接到远程MCP服务器(--transport).
• --model ：可重复；默认为 gpt-5, gpt-5.1, gpt-5-codex, gpt-5.1-codex，以及 claude-sonnet-4-5-20250929当您省略此标志时，CLI仅显示总计；指定一个或多个要关注的模型，输出将包括这些模型的详细工具细分。
• --anthropic-mode local|api 加 --anthropic-key （或 ANTHROPIC_API_KEY)允许您将克劳德测量值从局部近似值切换到Anthropic的官方测量值 count_tokens 端点，以便您可以准确地镜像Claude Code（API模式为每个工具发出一个请求，摘要显示本地令牌化器总数和API计数以进行比较）。使用 --anthropic-tool-prefix 可选择镜像Claude Code的 mcp____tool 在请求负载中重命名（默认为MCP服务器名称（如果可用））。
• --dump-tools / --print-schema：写出工具广告（到文件或stdout）。与配对时 --format json, --print-schema 将模式直接嵌入JSON有效负载中。
• --include-meta：保持 _meta 快照中的片段（默认情况下关闭以减少噪声）。
• --format table|json：人性化的表格或机器可读的JSON输出。
• --timeout / --max-retries ：微调 list_tools 以及HTTP重试行为。

跑 mcpusage --help 查看全套开关。

最小单工具MCP服务器（健全性检查）

为了在没有其他噪音的情况下检查克劳德的账目，我们在 fixtures/minimal-mcp:

cd fixtures/minimal-mcp
npm install
npm run build # optional; npm run dev works too

您可以将CLI指向它：

# Local tokenizer baseline
node dist/cli.js \
  --stdio-shell "cd fixtures/minimal-mcp && node dist/server.js" \
  --model claude-sonnet-4-5-20250929 --anthropic-mode local

# Anthropic `count_tokens` (mirrors Claude Code exactly; requires API key)
ANTHROPIC_API_KEY=sk-your-key node dist/cli.js \
  --stdio-shell "cd fixtures/minimal-mcp && node dist/server.js" \
  --model claude-sonnet-4-5-20250929 --anthropic-mode api

因为服务器只公开一个工具，所以您可以在Claude Code中注册它，运行 /context，并将“MCP工具”的使用情况与这些已知的总数进行比较。Claude赋予该工具的任何额外标记都表明，恒定的提示开销被捆绑到了他们的测量中。

代币计数的工作原理

1. 连接到MCP服务器并发出 list_tools，分页后，直到 nextCursor 是空的。
2. 按名称对生成的工具定义进行排序，并通过以下方式将其转换为JSON JSON.stringify.
3. 为每个请求的模型选择标记器。GPT-5具有原生 @dqbd/tiktoken 支持；GPT-5.1

目前，Codex变种映射到 o200k_base 直到OpenAI发布官方令牌。

1. 对序列化的JSON进行编码，并报告每个模型的令牌长度以及字节/字符计数。

这反映了PDF对预先计算代理“工具表面”成本的指导，以便您进行预算 在调用实际模型之前提示标记。

备注

• 需要Node.js 20+（带有顶级wait的ESM）。
• 未采取任何破坏性行动；该工具仅读取您指定的模式和可选输出路径。
• 警告和连接诊断已打印到stderr，因此 --format json stdout上保持干净。