# Whizbrew docs: connect an agent, call a tool, read the answer

> Whizbrew is one MCP server and one API for 893 live marketing data tools in 25 groups, paid per call: a typical call costs $0.002 ($2 per 1,000 calls), prices run from $0.001 to $0.52 a call, only a call that returns data is charged (an empty or failed call is free), and there is no subscription. A new account starts with $2 of free credit, about 1,000 typical calls, with no card.

## Connect

- **An agent on its own**: read [https://whizbrew.com/agents.md?a=2c8126223607](https://whizbrew.com/agents.md?src=body-text&a=2c8126223607). It asks for a free quote (`GET https://whizbrew.com/v1/agent/guide?goal=<the task in plain words>`), then one request (`POST https://whizbrew.com/v1/agent/start?a=2c8126223607`) gives it a key that works at once with the free credit, with no email and no sign-up form. Its human claims the account later.
- **A chat app** (ChatGPT, Claude, Gemini): add the MCP server `https://whizbrew.com/mcp` as a custom connector and sign in. No key to copy.
- **An agent with a shell** (Claude Code, Codex, Cursor): read [https://whizbrew.com/llms.txt?a=2c8126223607](https://whizbrew.com/llms.txt?src=body-text&a=2c8126223607). The agent starts a pairing with one request, its user approves with one click, and the agent holds its own key.
- **Plain HTTP**: create an account at [https://whizbrew.com/app#signup](https://whizbrew.com/app#signup), make a key, then `POST https://whizbrew.com/v1/call/<tool>` with `Authorization: Bearer <key>`.

MCP client config with a key:

```
{ "mcpServers": { "whizbrew": { "type": "http", "url": "https://whizbrew.com/mcp", "headers": { "Authorization": "Bearer <key>" } } } }
```

Every client step by step: [https://whizbrew.com/setup.md?a=2c8126223607](https://whizbrew.com/setup.md?a=2c8126223607).

## The MCP door

`https://whizbrew.com/mcp` (streamable HTTP, JSON-RPC 2.0). It lists a few tools in place of the whole catalogue:

- `search_tools`: plain words in, the tools that fit out, each with its price. Free.
- `describe_tools`: inputs, output, price and an example call for up to 10 tools. Free.
- `call_tool`: `{"tool": "<name>", "arguments": {…}}`. Charged only when it returns data.
- `get_balance`: the credit that is left. Free.
- `request_tool`: tell the team what is missing when no tool fits. Free.

Sign-in is OAuth 2.1 (discovery at `https://whizbrew.com/.well-known/oauth-protected-resource`) or an API key in `Authorization: Bearer`.

## The HTTP door

```
curl -s https://whizbrew.com/v1/tools                       # the catalogue, no key
curl -s -X POST https://whizbrew.com/v1/call/tiktok.profile \
  -H "Authorization: Bearer $WHIZBREW_KEY" -H "content-type: application/json" \
  -d '{"handle":"nasa"}'
curl -s https://whizbrew.com/v1/balance?a=2c8126223607 -H "Authorization: Bearer $WHIZBREW_KEY"
```

The routes as OpenAPI: [https://whizbrew.com/openapi.json?a=2c8126223607](https://whizbrew.com/openapi.json?a=2c8126223607).

## What an answer says

- `data`: the tool's answer. `meta.outcome`: `hit` (data, charged), `miss` (nothing found, free) or `error` (free).
- `meta.price_micros` and the header `X-Tapi-Cost-Micros`: what this call cost, in millionths of a dollar. `meta.balance_micros`: what is left.
- `X-Tapi-Request-Id`: the call's id, for support.
- Send `X-Tapi-Max-Cost-Micros` (MCP: `max_cost_micros`) to refuse a dearer call before it runs, and `Idempotency-Key` (MCP: `idempotency_key`) to send a call again without paying twice.

## Errors

Every error has `kind`, `message`, `blame` (`caller`, `us` or `source`), `hint` and, when waiting helps, `retry_after_s`. No error is charged. The table: [https://whizbrew.com/errors.md?a=2c8126223607](https://whizbrew.com/errors.md?a=2c8126223607).

## Limits

Up to 100 calls of an account run at once; more wait their turn for up to 10 seconds before they are refused with `rate_limited`. A spending cap per day or month can be set per account and per key.

## Catalogue and prices

893 tools in 25 groups: [https://whizbrew.com/tools?a=2c8126223607](https://whizbrew.com/tools?a=2c8126223607). Prices: [https://whizbrew.com/pricing?a=2c8126223607](https://whizbrew.com/pricing?a=2c8126223607). How often each tool works, from real calls: [https://whizbrew.com/status](https://whizbrew.com/status).
