Skip to main content

hermes-mpp

❖ Communityv0.1.3+a0782b7★ 2

Tools · by tempoxyz · added

Pay supported HTTP 402 MPP challenges on Tempo through mpp_fetch and in-process HTTPX clients. Uses a dedicated wallet.

Open in Hermes Desktop
hermes plugins install hermes-mpp
Repository ↗Reviewed source @ a0782b7 ↗Documentation ↗

What it adds

Tools 1

mpp_fetch

Environment variables it needs 1

TEMPO_PRIVATE_KEY

README

From the reviewed commit a0782b7 ↗; it updates when the author re-pins.

MPP for Hermes Agent

PyPI CI License

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

← Back to the catalog · catalog built Oct 8, 2026