MPP for Hermes Agent

hermes-mpp makes Hermes Agent HTTPX traffic payment-aware. It answers supported MPP 402 challenges with a Tempo charge and retries the request through the same client.

Maintained by Tempo, the team behind MPP.

[!IMPORTANT] This is experimental v0 software. It can authorize real payments automatically with the configured Tempo key. Use a dedicated, low-balance key and restrict allowed origins.

v0 targets Hermes Agent 0.19, HTTPX 0.27–0.28, and pympp 0.10.

Install

After installing Hermes, run:

uvx hermes-mpp install --allowed-origin https://mpp.dev

The installer adds and enables the plugin, then prompts for a Tempo private key; leave it blank to generate one. It stores the key in ~/.hermes/.env with owner-only permissions, saves each --allowed-origin, and prints the address to fund.

The installer discovers standard, root, and PATH-based Hermes installations. For a custom environment, run uvx hermes-mpp install --hermes-python PATH or set HERMES_PYTHON.

Generated wallets start empty. For testnet resources, fund the printed address with the Tempo faucet.

On first install, omitting --allowed-origin allows any origin presenting a valid MPP challenge to charge the wallet. Repeat the option to allow multiple exact origins. Reinstalling without it preserves the allowlist; passing it replaces the list.

Paths and wildcards are rejected. Use plaintext http:// only for trusted local development; an on-path attacker can inject a payment challenge.

Use

Ask Hermes for the resource normally:

hermes chat -q "Make a request to https://mpp.dev/api/ping/paid"

The model gets one generic mpp_fetch tool for arbitrary HTTP APIs. Payment is not a separate tool call: it and every other in-process HTTPX client handle supported MPP challenges automatically.

Behavior

• Existing and future sync and async clients retain their transport, pool, cookies, hooks, redirects, extensions, and streaming behavior. Response hooks observe the final logical response rather than the internal 402.
• Free responses pass through. Malformed, unsupported, and disallowed challenges remain ordinary 402 responses.
• A paid request is retried at most once. Distinct payments are serialized; equivalent, repeated, and uncertain attempts fail closed.
• mpp_fetch blocks private-network redirects, hides sensitive response headers, and truncates large bodies.
• Only HTTPX traffic in the Hermes process is instrumented. Shell commands and Requests, aiohttp, or urllib3 are not; use mpp_fetch for arbitrary HTTP.

If a payment outcome is uncertain, verify the wallet transaction before restarting Hermes; later payments remain blocked in that process.

Manage

hermes plugins list
uvx --refresh hermes-mpp install  # update
uvx hermes-mpp uninstall

Uninstalling leaves the private key in Hermes's .env file.

Develop

uv sync
uv run pytest
uv run ruff check .

CI tests Python 3.11–3.13 and HTTPX 0.27–0.28.

Security

Report vulnerabilities privately as described in SECURITY.md.

License

MIT