docs(catalog): Commerce MCP — sandbox test merchants, get_service requestShape, pay_service method

[r-marques]

Description

Companion to nevermined-io/nvm-monorepo#3547 (issue nevermined-io/nvm-monorepo#3528).

• products/catalog/mcp.mdx — a Sandbox row in the environments table, a tip on the two free testnet test merchants the sandbox Catalog carries (mpp-dev-paid-ping — MPP, Tempo Moderato, GET, $0.10 testnet pathUSD; x402-org-protected — x402, Base Sepolia, GET, $0.01 testnet USDC), the get_service requestShape block (per-endpoint path / method / price with exact payServiceArgs; bodySchema: null because the Catalog holds no request-body schema), pay_service method resolution (caller → catalog endpoint matching path → POST) and its echoed request block. The stale nativeEndpoint signpost example is corrected: no upstream URL is returned since the opaque broker.
• discover.mdx, router/quickstart.mdx, from-a-harness.mdx — the "Live-only for payment / nothing payable on sandbox" statements are qualified with the test-merchant exception and a link to the MCP page, so they stop being false the day the seed lands.

⚠️ Merge timing: the two sandbox rows arrive with the nvm-monorepo release that carries #3547's SeedSandboxTestnetMerchants migration. Until that release is deployed to api.sandbox.nevermined.app, the tip describes rows that are not there yet — hold this PR until then (or merge #3547 first and wait for the release).

mintlify broken-links: no broken links found.

🤖 Generated with Claude Code

---

2026-09-21 — out of draft. Production is enabled and in effect (argocd#646 merged + synced; connect/details → ["commerce"] on both prod tiers), so the gate these drafts waited on is met. Stacked PR: base = #409 (docs/3394-cimd-trust-overlay); #414 follows. Rebased onto the current pages (main restructured for-agents.mdx / overview.mdx and grew mcp.mdx meanwhile); mintlify broken-links green. Merge in order — GitHub retargets each base to main as the previous one lands.

[eruizgar91]

👀 pr-review-bot (fallback) picking this up.

[eruizgar91]

Reviewed the diff against this PR's own base (docs/3394-cimd-trust-overlay), not main — 4 files, +21/-11. Every factual claim was checked against the shipped system rather than for internal consistency: the seed migration (libs/database/src/migrations/1800001300000-SeedSandboxTestnetMerchants.ts), the MCP source (apps/mcp/src/mcp/{request-shape,pay-service,mcp.server}.ts), the argocd MCP Applications, and live read-only probes of api.sandbox.nevermined.app and mcp.sandbox.nevermined.app.

4 findings posted inline (3 MEDIUM, 1 LOW). All are bounded one- or two-sentence edits inside products/catalog/mcp.mdx; nothing needs a follow-up issue.

Verified correct (live evidence, so these can be treated as settled):

• Both rows exist on prod sandbox and are absent from live (404 on both slugs at api.live.nevermined.app). mpp-dev-paid-ping — protocol: mpp, network: "Tempo Moderato (testnet)", priceLabel: "$0.10 (testnet pathUSD)", one endpoint {path:"/", method:"GET"}; x402-org-protected — protocol: x402, "Base Sepolia (testnet)", "$0.01 (testnet USDC)", one endpoint {path:"/", method:"GET"}. Both isListed: true, both tagged testnet.
• "listed last" holds: both carry tier: 4 while every other row defaults to tier: 3, and the default listing orders tier ASC first — fetched page 2 of the sandbox catalog and they are positions 72 and 73 of 73. (It is a property of the default view only; an explicit sortBy opts out. Not worth qualifying on the page.)
• "pay_service with just the slug settles against either" — correct: each has a single root endpoint, and matchEndpoint with no path resolves the root entry, so methodSource is catalog and the method is GET.
• https://mcp.sandbox.nevermined.app/mcp is a real deployed host (production-mcp-sandbox.yaml, service.hostname: mcp.sandbox.nevermined.app); initialize answers 200. MCP_EMBED_BASE_URL / MCP_EMBED_NETWORK are set on it, so setup_delegation works there too.
• requestShape / bodySchema: null / the unknown — the catalog holds no request schema note (a correct prefix of REQUEST_SHAPE_UNKNOWN_NOTE), the request block's four key names, the three methodSource literals caller / catalog / default, the method-resolution order, search vs path, maxTotalCents, and the removal of nativeEndpoint (the payable:false branch really does return exactly payable / protocol / priceLabel / network / note) — all match the code.
• The three qualifier edits in discover.mdx, router/quickstart.mdx and from-a-harness.mdx are accurate, and the /products/catalog/mcp#1-connect-your-host anchor resolves to the ### 1. Connect your host heading on the head revision.

Considered and discarded:

• requestShape.endpoints[] carries more keys than the page names (description, pathParams, and optionally invokePath, requestExample, responseFields, contractEvidence, endpointCheck) — the bullet is a prose summary, not a schema, and naming the load-bearing three is the right altitude. Not a defect.
• payServiceArgs omits path for a root endpoint — matches what the tool emits; the next paragraph explains bare-slug calls.
• Quoting only the prefix of the "unknown" note — the quoted fragment is literally how the string starts, and the page does not claim it is the whole note.
• An unlisted / pending row returns service_not_found, not payable:false (the public catalog read filters on isListed: true) — true, but the page does not claim otherwise; out of scope here.

On the merge-timing caveat in the PR description: it is already satisfied. Both rows are live on api.sandbox.nevermined.app today (createdAt: 2026-09-16T07:59:10Z), so the tip no longer describes rows that are not there yet.

[eruizgar91]

🟡 Approved with comments — no blockers; 3 should-fix, 1 nit(s) left inline.

Inline review: #411 (review)