halowerk-mcp

halowerk-mcp

70 paid APIs as MCP tools. No account, no login, no subscription — a throwaway wallet with a few dollars is enough.

Your spend is capped before anything is signed:

Variable	Default	What it does
HALOWERK_MAX_PREIS_USDC	0.05	Ceiling per call. A more expensive service is refused, not silently bought.
HALOWERK_BUDGET_USDC	1.00	Ceiling per session. Once reached, the server refuses further calls.
HALOWERK_TROCKEN	off	Dry run: returns the price and the call plan, pays nothing.

Every paid answer carries bezahlt_usdc, budget_rest_usdc and the transaction hash, so the model and you see the same numbers.

---

Try it without a wallet

Two tools work with no wallet and cost nothing: halowerk_katalog lists every service with its price, and halowerk_preis tells you what a planned call would cost. Install it, browse, decide later.

{
  "mcpServers": {
    "halowerk": { "command": "npx", "args": ["-y", "halowerk-mcp"] }
  }
}

That goes in your Claude Desktop config (claude_desktop_config.json), Cursor's mcp.json, or Cline's MCP settings.

Paying for calls

{
  "mcpServers": {
    "halowerk": {
      "command": "npx",
      "args": ["-y", "halowerk-mcp"],
      "env": {
        "HALOWERK_PRIVATE_KEY": "0x…",
        "HALOWERK_MAX_PREIS_USDC": "0.05",
        "HALOWERK_BUDGET_USDC": "1.00"
      }
    }
  }
}

Payment is x402 with USDC on Base. There is no account to create, no card, no invoice: the call carries a signed authorisation for the exact amount, and the service settles it.

Use a throwaway wallet

Create a fresh wallet, put a few dollars of USDC on it, use it for nothing else.

Not because this package is untrustworthy — because you have no reason to trust it yet. A key in an MCP config is a key that a model-driven process can reach. The way to make that safe is not to trust the code but to make the blast radius small: if the wallet holds three dollars, three dollars is the worst case.

You do not need ETH for gas. Payment uses EIP-3009 transferWithAuthorization, so a third party submits the transaction. A balance of exactly 0 ETH is normal and correct.

What the code does with your key

• It is read from HALOWERK_PRIVATE_KEY and from nowhere else — no file, no argument, no prompt.
• It is never logged, never put in an error message, never returned in an answer, not even truncated. There is a test for this: npm run pruefe searches the entire output for the first eight characters of a key and fails if it finds them.
• src/x402.ts is about 300 lines and is the only file that touches it. It is meant to be read in five minutes.

Where your money can go

The server only ever pays the ten hosts baked into the catalogue at build time. The list is frozen in the package; it cannot be extended by a file, an environment variable or a tool argument.

This is the point of the whole design. A tool that accepts an arbitrary URL and pays for it is a payment instruction with a blank payee field. A model that reads a web page, a PDF or an email can be told, by that text, to call such a tool with an attacker's address. So:

• The target host must match the built-in list exactly. No suffix comparison — halowerk.com.attacker.example passes any endsWith check and is a different host.
• https only. Redirects are not followed: a 301 to a foreign host is the attack, not an inconvenience.
• No IP addresses, no localhost, no private ranges.
• On violation: refusal with the reason, before anything is signed.

halowerk_rufe_auf takes a tool name from the catalogue, never a URL.

Modes

Seventy tools at once makes the tool picker worse for everybody, especially if you have other MCP servers connected. So:

HALOWERK_MODUS	Tools	For
hero (default)	12 services + the 2 free ones	Everyday use
gateway	3 meta-tools + the 2 free ones	Minimal context; two extra round trips
all	70 services + the 2 free ones	You know what you want

In gateway mode: halowerk_suche finds a service by description, halowerk_beschreibe returns its input schema, halowerk_rufe_auf executes it.

Why these twelve

One measure only: what does an agent need more than once in the same task? A tool used once per session can be looked up; one used ten times belongs in the toolbox. All twelve are also text in, text out — in a chat window, a tool that needs a file upload first is close to unusable.

Tool	Repeats because
cost_estimate	before every model call
output_validate	after every model answer
tool_arg_validate	before every expensive or irreversible call
state_store	across every step of a long task
cve_check	per dependency list, and you look at it more than once
license_check	same audit, per package set
tls_chain	per host in an infrastructure check
jwt_verify	per token while debugging auth
webhook_signature	per webhook while debugging an integration
doc_diff	per file pair in a review
web_archive	per URL in a research task
invoice_audit	per invoice in a batch

Tiered prices — read this before you set a budget

Some services bill per unit: per audio minute, per 1000 characters, per sample point. For those, price_usdc is only the minimum.

The budget check therefore uses max_usdc, the ceiling. Checking against the minimum would approve 0.006 and pay 0.25 — the endpoint bills by length, and the length is in the request body, not in the catalogue.

If a service has no ceiling at all, it counts as unbounded and is not called without unbegrenzt_erlauben: true. A budget that checks against an unknown amount is not a budget.

What this package is not

• It is not a wallet manager. It signs payments; it never moves funds anywhere else.
• It does not create or store keys.
• It does not phone home. The only outbound requests go to the ten catalogue hosts.
• The catalogue is generated from the live services and shipped with the package. It is not fetched at runtime, so a compromised server cannot add itself to your allowlist between calls.

Development

npm run katalog   # regenerate katalog.json from the live services
npm run build     # compile TypeScript
npm run pruefe    # modes, spending brakes, attack tests, key-leak test

katalog.json is generated. Never edit it by hand — regenerate and republish, otherwise the package promises a price the service does not charge.

License

MIT. See LICENSE.