batchwatch-mcp

batchwatch MCP server

Let an AI agent ask batchwatch "should I batch this job?" instead of guessing.

When a developer asks Claude, Cursor, Cline or any MCP-speaking agent "should I send this to the batch queue or run it synchronously?", this server lets the agent call batchwatch and get the real queue evidence — the measured wait distribution, the current conditions, a graded confidence, and how fresh the data is.

It wraps batchwatch's existing read routes as MCP tools. It is a thin, faithful proxy: it makes no decision and invents no numbers. Every answer is the provider's own JSON, passed through verbatim, carrying the n, confidence, why, basis and freshness the API already returns. If the API is down or slow, the tool returns an error — never a fabricated figure.

Access & tiers — the same gate as the rest of batchwatch

Because it is a faithful proxy, the server runs on the same tiers as the batchwatch API — there is no separate MCP plan and no MCP fast lane. Each tool carries your BATCHWATCH_TOKEN and earns exactly the tier that key earns anywhere else:

• No token → you read the public data, delayed 15 minutes. You still get every answer — the distribution, the conditions, the verdict — as fresh as the open API serves them.
• A token → the agent earns that key's tier and its freshness, volume and live behaviour. Live figures are what let an agent route real traffic on the answer, and they are bought here the same way they are bought at the API.

One access model, gated in one place — the batchwatch tier system (see the Tiers, delay, quota and the free trial reference in the batchwatch API docs).

Tools

Each tool maps to a real route in src/index.js (there is deliberately no tradeoff tool — /v1/tradeoff is named in the KRAVSPEC but not built yet, and a tool for a route that does not answer would be exactly the fabricated capability this project refuses to ship).

Tool	Route	What it answers
should_i_batch	GET /v1/should-i-batch	Given a model and your own max_wait, does the batch queue currently honour it? The verdict.
estimate_batchtime	GET /v1/estimate-batchtime	How long is my job likely to wait? A distribution, never a single ETA.
conditions	GET /v1/conditions	Current conditions vs the recent norm — "is it me or them?"
distribution	GET /v1/distribution	The full measured wait distribution (the raw evidence).
coverage	GET /v1/coverage	Which provider+model combos have data, and how answerable each is.
wait	GET /v1/wait	The public "is the queue moving now?" reading (delayed without a key).

batchwatch reports distributions and current conditions, not point ETAs. A personal history of 3-minute medians once produced a 480-minute job; "your job finishes at 14:32" is a lie the one time it matters. The tools' descriptions say so, so the calling model uses the answer correctly.

Install & run

cd mcp
npm install
node index.js       # speaks MCP over stdio

Requires Node ≥ 18 (uses the built-in fetch).

Configuration (environment)

Var	Default	Meaning
BATCHWATCH_URL	https://batchwatch.dev	API base.
BATCHWATCH_TOKEN	(unset)	Optional API key. Without it the data is delayed, not absent — you still get answers, just older ones.
BATCHWATCH_TIMEOUT_MS	8000	Per-call timeout. On timeout the tool errors; it never guesses.

Wiring into a client

Claude Desktop / Cursor / Cline mcpServers entry:

{
  "mcpServers": {
    "batchwatch": {
      "command": "node",
      "args": ["/absolute/path/to/batchwatch/mcp/index.js"],
      "env": { "BATCHWATCH_TOKEN": "tk_your_key_optional" }
    }
  }
}

Tests

npm test                      # offline unit tests (mocked fetch) — deterministic
BATCHWATCH_LIVE=1 npm test    # also runs the live smoke against BATCHWATCH_URL

The unit tests assert the load-bearing properties: omitted numeric fields are never sent as 0; the provider JSON is passed through unchanged; only the real routes are exposed (no tradeoff); and an API error yields an error, never a number.

Publishing (registry reach — the point of #57)

The highest-leverage distribution channel for a 2026 dev tool is being the answer an agent reaches for by default. Once this is published so agents can install it, batchwatch wins the call instead of merely being mentioned. Targets: the Anthropic MCP registry, Smithery, and mcp.so. The package is publish-ready (bin: batchwatch-mcp, zero build step); registry submission is tracked on Vikunja task #57.

Why this exists

batchwatch measures how long jobs actually wait in LLM providers' async batch queues. Batch is half price, but "done within 24 hours" cannot be planned around, so most callers pay full price out of habit. This server puts the queue evidence one tool-call away from the agent that is about to make that choice.