phm-aguiar/planejamento/mpp-agent

MPP Agent Skill

Wraps the Machine Payments Protocol (MPP, https://mpp.dev) clients so Hermes can pay for per-request API access against servers that respond with HTTP 402 Payment Required.

Three client options, all distributed via npm. Pick the lightest one that solves the user's need. Gated [linux, macos] while the broader payments tooling matures on Windows.

When to Use

• A merchant API returns HTTP 402 with a www-authenticate header — and the user wants to actually pay it, not just log the response.
• The user asks to "pay per request", "set up an agent wallet", "use Tempo / Privy / AgentCash", or wants to discover MPP-priced services.
• A Stripe Link spend has produced a Shared Payment Token (SPT) and the agent needs to attach it to the 402 challenge — in that flow, prefer link-cli mpp pay (see the stripe-link-cli skill).

Choosing a client

Default: if the user already has Stripe Link configured or the 402 challenge specifies method="stripe", use link-cli mpp pay (the stripe-link-cli skill). Otherwise mppx for one-off paid calls and debugging, and Tempo Wallet when the user wants persistent spend controls.

Prerequisites

• Node.js 20+ on PATH
• A funded wallet (Tempo / Privy / AgentCash) OR an mppx account
• For Tempo / Privy / AgentCash: follow their respective onboarding skills:
• https://tempo.xyz/SKILL.md
• https://agents.privy.io/skill.md
• https://agentcash.dev/skill.md

Use web_extract to fetch any of those SKILL.md files if the user picks one.

Procedure (mppx, fastest path)

Run all commands through the terminal tool.

1. Install + create an account

npm install -g mppx
mppx account create

Store the resulting account credentials wherever the CLI tells you (the CLI writes them under its own config — do not paste them into the agent transcript).

2. Inspect the merchant's 402 challenge

If the user gives you a URL, probe it first to confirm it actually speaks MPP:

curl -i <url>

A real MPP 402 looks like:

HTTP/1.1 402 Payment Required
www-authenticate: tempo amount=0.1 currency=...

3. Pay the request

mppx <url>

For non-GET methods or request bodies:

mppx <url> --method POST --data '<json>'

mppx handles the 402 challenge/credential dance automatically and prints the merchant's actual response on success.

4. Verify the receipt

mppx attaches the receipt header automatically. To inspect:

mppx <url> -v

Procedure (Tempo Wallet)

The Tempo Wallet skill at https://tempo.xyz/SKILL.md is the canonical reference; fetch it with web_extract and follow it. Headline:

tempo wallet login
tempo wallet pay <url>

Spend controls and service discovery live in the wallet UI at https://wallet.tempo.xyz.

Pitfalls

• `HTTP 402` without `method="stripe"` cannot be paid by Stripe Link. If the challenge advertises only Tempo / other methods, use mppx (or whichever wallet matches) — Link will reject it. Conversely, if it advertises method="stripe", prefer Link via the stripe-link-cli skill so the spend goes through the user's approved card.
• Multiple challenges in one header. www-authenticate may list several methods (e.g. tempo, stripe). The Link CLI's mpp decode will pick the Stripe one; mppx will pick Tempo. There's no single "right" client — pick by which wallet the user has funded.
• Zero-amount challenges. Some MPP endpoints charge $0.00 and just want a proof credential. These work without a funded wallet. Don't refuse them as "broken."
• Wallet keys never enter agent context. All four clients store keys under their own config dirs (or generate per-session ephemeral keypairs, in Privy's case). Do not cat/read_file them.
• Server-side MPP is a different skill. If the user wants to ADD 402 to their own API, this skill is wrong — point them at https://mpp.dev/quickstart/server and the mppx/nextjs / mppx/hono / mppx/express / mppx/elysia middlewares. A dedicated mpp-server skill may land later.

Verification

mppx --version && mppx account list

Exit code 0 means installed and an account exists.