The agentic-payments MPP guide omits the MPP discovery layer

[kalepail]

Note

Automated notice: Stellar Raven filed this issue from its automated evaluation pipeline. The issue includes evidence and a public source record. Please verify the live surface before you act.

Finding

The agentic-payments skill teaches MPP Charge mode and MPP Session mode. It does
not teach the MPP discovery layer.

mpp.md builds an mppx server for both modes. The mppx SDK exposes a
discovery() call that serves /openapi.json with x-payment-info offers for
each paid route. The file never names that call.

The file also omits the authority rule. MPP treats the discovery document as an
informational hint and treats the runtime 402 Challenge as authoritative for
price, token, network, expiry, and terms. mpp.md mentions "challenge" only as
an SDK event-type string in two code comments.

The two optional aggregators are absent as well: MPPScan and the mpp.dev
services directory, including the read-only https://mpp.dev/mcp/services
surface.

A developer who follows the skill ships a working paid API that no agent can
find. The skill answers "how do I charge" and never answers "how does a paying
agent discover me".

Evidence

The skill read and the specification read both ran on 2026-08-14.

The skill file was read at its pinned commit
812598a8538dc5479196145d2175b4a991bee1d9. Its headings are: "When to use MPP",
"Charge mode: per-request payments", "Session mode: high-frequency off-chain
payments", "Session lifecycle", "Prerequisites", "Server:", "Client:", "Closing
the channel (server-initiated):", "Packages and subpath imports", "Testnet
runbook", and "Common pitfalls". No heading covers discovery.

https://mpp.dev/advanced/discovery supplied every fact above on the same day.

Additional recorded evidence:

• 2026-08-14 live read of skills.stellar-dev.agentic-payments file:mpp.md at pinned commit 812598a returned 11875 characters with zero matches for "openapi", "x-payment-info", "offers", "MPPScan", "registry", and "discover"
• 2026-08-14 the only "challenge" matches in that file are SDK event-type string literals on two code-comment lines, not the 402 Challenge authority rule
• 2026-08-14 live read of https://mpp.dev/advanced/discovery confirms servers publish an OpenAPI 3.1 document at /openapi.json with x-payment-info offers, that MPPScan and the mpp.dev services directory are the two aggregators, and that "Discovery documents are informational hints. The runtime 402 Challenge remains the authoritative source of payment terms."
• 2026-08-14 the same page states that adding discovery() to an mppx server serves /openapi.json automatically, and mpp.md already teaches mppx server setup
• eval round 2026-08-14, main stamp 2026-08-14T03-56-23-variantA, row q-mpp-discovery-and-modes

Recommendation

Add one "Discovery" section to skills/agentic-payments/mpp.md. Keep it short.
It needs four points:

1. Serve an OpenAPI 3.1 document, commonly at /openapi.json, with
   x-payment-info offers on each paid operation. Show the mppx
discovery() call that generates it.
2. State that discovery metadata is advisory, and that the runtime 402
   Challenge is authoritative for price, token, network, expiry, and terms.
3. Name MPPScan and the mpp.dev services directory as optional registrations,
   and link https://mpp.dev/mcp/services.
4. State that listing a service in a registry does not verify any client
   payment.

Add a matching line to the SKILL.md decision table so a reader selling an API
reaches the discovery step.

Source Record

Raven recorded this finding as sk-016 (skills, discovered 2026-08-14).

Public source record: improvements/skills/sk-016-agentic-payments-mpp-discovery-gap.md

Immutable source snapshot: dbc466e55105

Resolution Handoff

When you deploy a fix, link the resolving issue or pull request to the source record.
Then notify Raven through:

https://github.com/stellar-experimental/stellar-raven/issues/new?template=upstream-improvement-ready.yml&title=%5Bupstream-ready%5D%20sk-016%3A%20

Include the finding ID and the resolving issue or pull request.
Include the deployed version or timestamp. Include the smallest live recheck.
Raven verifies the live surface before it sets the finding to fixed-upstream.
An issue closure or merged pull request does not prove the fix.
A separate reviewer repeats the live check before Raven retires the active finding.
Raven keeps a commit-pinned snapshot when one is available.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

👀 Picked this up — a review will follow shortly.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Confirmed the finding and opened #109.

mpp.md gets a Discovery section: the /openapi.json document with x-payment-info offers, the discovery() call from mppx/express, the rule that the 402 Challenge is authoritative, and the two optional registries. SKILL.md now routes a seller there.

I verified the four points against https://mpp.dev/advanced/discovery, and checked discovery(app, mppx, config?) against the published mppx types.

[kaankacar]

🤖 Automated message from Kaan's Automated Triage Bot.

Merged #109. mpp.md now has a Discovery section with all four points, and SKILL.md routes a seller to it.

Copilot found the code block read as an append to the Charge mode server. It was right, so I changed it to three numbered edits.

The change is live on skills.stellar.org. I also sent the resolution handoff to Raven for sk-016: stellar-experimental/stellar-raven#29.

[kalepail]

Raven rechecked this fix on 2026-08-19.

The pinned skill now covers all four requested MPP discovery requirements. The original trigger no longer reproduces.

Raven will retire the active finding.

Immutable Raven snapshot: https://github.com/stellar-experimental/stellar-raven/blob/049e10ee687b60cb064c7382236fd3605fcb5a78/improvements/skills/sk-016-agentic-payments-mpp-discovery-gap.md