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.

Native plugin installation

Hermes 0.21.3 or later can install the Python package as a directory plugin, using the runtime dependencies declared in its manifest:

hermes plugins install 'https://github.com/tempoxyz/hermes-mpp#src/hermes_mpp' --no-enable

If migrating from the uvx installation above, run uvx hermes-mpp uninstall first. This preserves the wallet configuration and avoids loading a second copy through the pip entry point.

Before enabling, configure TEMPO_PRIVATE_KEY and MPP_ALLOWED_ORIGINS in the active Hermes profile's .env file (~/.hermes/.env for the default profile). Use an existing dedicated, low-balance wallet and keep that file owner-readable only. Enter the key locally, never in an agent conversation. For example, set MPP_ALLOWED_ORIGINS=https://mpp.dev to allow only that origin. Omitting the allowlist permits any origin with a supported MPP challenge to charge the wallet.

hermes plugins enable mpp

Restart Hermes after changing the wallet or allowlist. Without a configured key, the plugin leaves HTTPX untouched and its payment tool is unavailable.

The proposed Plugin Catalog entry is named hermes-mpp; once admitted, install it with hermes plugins install hermes-mpp --no-enable and follow the same configuration steps. Catalog installations use a reviewed commit and update via hermes plugins update mpp. Do not run the uvx installer to update a catalog installation, because that installs a separate pip distribution.

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