mcp tokens

Estimate MCP token usage for server capabilities by connecting to servers and analyzing their tools, resources, and prompts.

For a complete overview of server management, see the Server Management Guide.

Synopsis

npx -y @1mcp/agent mcp tokens [options]

Options

• --model, -m <model>

  • Model to use for token estimation (default: gpt-4o)
  • Supports any valid tiktoken model including gpt-3.5-turbo, gpt-4, o1, etc.

• --preset, -p <name>

  • Use preset filter instead of manual tag expression
  • Cannot be used together with --tag-filter

• --tag-filter, -f <expression>

  • Filter servers by advanced tag expression (and/or/not logic)
  • Examples: network, web+api, (filesystem,network)-test
  • Cannot be used together with --preset

• --format <format>

  • Output format: table, json, summary (default: table)

• --verbose, -v

  • Show server logs and connection details
  • By default, server logs are suppressed for clean output

• --config, -c <path>

  • Path to the config file

Description

The mcp tokens command connects to your configured MCP servers and analyzes their capabilities to estimate token usage. This is useful for:

• Cost Planning: Estimate token costs when using different language models
• Performance Analysis: Understand which servers contribute most to token usage
• Optimization: Identify opportunities to reduce token consumption
• Debugging: Analyze server connectivity and capability loading

The command uses tiktoken for accurate tokenization based on the specified model, with automatic fallback handling for invalid models.

Examples

# Estimate tokens for all MCP servers using default model (gpt-4o)
npx -y @1mcp/agent mcp tokens

# Use a different model for token estimation
npx -y @1mcp/agent mcp tokens --model gpt-3.5-turbo

# Use a preset for server filtering
npx -y @1mcp/agent mcp tokens --preset development

# Filter servers by tags and show summary format
npx -y @1mcp/agent mcp tokens --tag-filter="network or filesystem" --format=summary

# Export detailed analysis as JSON for programmatic use
npx -y @1mcp/agent mcp tokens --format=json > token-analysis.json

# Complex tag filtering with specific model
npx -y @1mcp/agent mcp tokens --model=o1 --tag-filter="(web+api)-test" --format=table

# Show server logs and connection details for debugging
npx -y @1mcp/agent mcp tokens --verbose

# Use custom config file
npx -y @1mcp/agent mcp tokens --config ~/my-mcp-config.json

Output Formats

Table Format (Default)

Shows a beautifully formatted, colorful hierarchical breakdown by capability type (Tools, Resources, Prompts) with server groupings and token estimates for each item. The output uses:

• Colored sections with visual icons (🔧 Tools, 📁 Resources, 💬 Prompts)
• Boxed summary with overall statistics
• Clean layout with server logs suppressed by default
• Connection status clearly indicated for each server

JSON Format

Provides structured data suitable for programmatic analysis:

{
  "summary": {
    "totalServers": 5,
    "connectedServers": 4,
    "totalTools": 25,
    "overallTokens": 8450
  },
  "servers": [
    {
      "serverName": "filesystem",
      "connected": true,
      "breakdown": {
        "tools": [...],
        "totalTokens": 1200
      }
    }
  ]
}

Summary Format

Concise overview with key metrics and top servers by token usage, presented in colorful boxed sections:

• Usage summary with server counts and capability totals
• Top servers ranking by token consumption
• Connection issues clearly highlighted if any servers are down

Supported Models

The --model option accepts any valid tiktoken model:

• GPT-4 Family: gpt-4o, gpt-4, gpt-4-turbo
• GPT-3.5 Family: gpt-3.5-turbo, gpt-3.5-turbo-16k
• O1 Family: o1, o1-mini, o1-preview
• Legacy Models: text-davinci-003, code-davinci-002

If an invalid model is specified, the command automatically falls back to gpt-4o with a warning.

Error Handling

• Server Connection Failures: Displayed in output with error details
• Invalid Model Names: Automatic fallback to gpt-4o
• Configuration Issues: Clear error messages with suggested fixes
• Permission Errors: Helpful guidance for authentication issues

See Also

• Server Management Guide
• mcp status - Check server connectivity
• mcp list - List configured servers