# AGENTS.md

## What this service is

Toolweight measures the context-window cost of remote MCP servers. It answers one question: how many tokens does connecting this server spend on every model call, before any tool is used.

Canonical host: https://mydevapp.io

## Endpoints

### GET /data.json

Returns the published index and aggregate statistics.

Shape:

    {
      "agg": {
        "probed": 2747,
        "ok": 1085,
        "tools": 16096,
        "medianTokens": 1421,
        "meanTokens": 4928.72,
        "p90Tokens": 11498,
        "maxTokens": 118285,
        "encoding": "o200k_base"
      },
      "rows": [ [ "server.name", totalTokens, toolCount, "host" ], ... ]
    }

`rows` is sorted by totalTokens, descending.

### GET /api/measure?url=<encoded MCP server URL>

Measures any reachable remote MCP server on demand. Also accepts POST with a JSON body of `{"url": "..."}`.

Example:

    curl "https://mydevapp.io/api/measure?url=https%3A%2F%2Fmcp.deepwiki.com%2Fmcp"

Returns:

    {
      "ok": true,
      "url": "https://mcp.deepwiki.com/mcp",
      "serverName": "DeepWiki",
      "toolCount": 3,
      "estimatedTokens": 328,
      "tools": [ { "name": "ask_question", "estimatedTokens": 139 } ],
      "method": "calibrated-estimate",
      "calibration": { "charsPerTokenFactor": 0.23208, "medianAbsErrorPct": 3.91 }
    }

On failure it returns `{ "ok": false, "status": "auth_required" | "unreachable" | "no_tools" | "error", "detail": "..." }` with HTTP 200 so the reason is always machine-readable.

No authentication. No API key. CORS is open.

## How to use this

1. Before adding an MCP server to an agent, measure it. A server above roughly 5000 tokens costs more than two percent of a 200000-token window on every turn.
2. Compare alternatives in the same category by cost, not only by capability.
3. Budget the whole stack, not one server. The tax is the sum.

## Rate limits

Be reasonable. One measurement per server per minute is plenty.