@oobe-protocol-labs/sap-mcp-server 0.3.0 → 0.7.1

package/.env.example

@@ -144,6 +144,9 @@ SAP_MCP_FACILITATOR_PATH_PREFIX=/facilitator
 SAP_MCP_FACILITATOR_NETWORKS=devnet
 # SAP_MCP_FACILITATOR_SIGNER_PATH=~/.config/mcp-sap/keypairs/oobe-x402-facilitator-keypair.json
 # SAP_MCP_FACILITATOR_RPC_URL=https://api.devnet.solana.com
+# Optional comma-separated RPC fallbacks. Keep API keys private and server-side.
+# The facilitator also appends the public Solana RPC for each configured network.
+# SAP_MCP_FACILITATOR_RPC_FALLBACK_URLS=https://api.devnet.solana.com
 # SAP_MCP_FACILITATOR_AUTH_TOKEN=
 
 # Initial pricing:

package/CHANGELOG.md

@@ -2,6 +2,217 @@
 
 All notable changes to this project are documented in this file.
 
+## [Unreleased]
+
+## 0.7.1 - 2026-07-13
+
+### Highlights
+
+Publishes SAP MCP as a registry-ready MCP server with official metadata for
+the Model Context Protocol Registry, while shipping the MagicBlock tool suite
+that was previously staged under `Unreleased`.
+
+### Added — MCP Registry
+
+- Added `mcpName: ai.oobeprotocol.sap.mcp/sap-mcp` to package metadata so
+  the npm package can be verified by the MCP Registry through OOBE Protocol's
+  domain ownership.
+- Added root `server.json` using the official MCP Registry server schema,
+  with hosted `streamable-http` remote metadata for
+  `https://mcp.sap.oobeprotocol.ai/mcp` and local npm stdio package metadata.
+- Added `GET /.well-known/mcp-registry-auth` support for MCP Registry
+  HTTP domain authentication via `SAP_MCP_REGISTRY_AUTH_RECORD` or
+  `SAP_MCP_REGISTRY_AUTH_FILE`.
+- Added repository, homepage, bugs, and packaged `server.json` metadata to
+  the npm package for registry and client discovery.
+
+### Added — MagicBlock Tools (20 tools, 3 protocols)
+
+New `magicblock-tools.ts` module registering 20 MagicBlock tools with the
+MCP server, covering ER Router (JSON-RPC), Private Payment API (REST),
+and Solana VRF (on-chain via @solana/web3.js).
+
+**Tools added:**
+
+- `src/tools/magicblock-tools.ts` — 20 tools with JSON Schema input
+  definitions, stateless HTTP client (global `fetch`, zero external deps),
+  error handling with structured responses, and per-tool pricing metadata.
+- `src/tools/__tests__/magicblock-tools.test.ts` — 10 smoke tests
+  verifying tool registration, schema shapes, pricing, and handler
+  presence.
+
+**Files modified:**
+
+- `src/tools/index.ts` — export `registerMagicBlockTools`
+- `src/tools/register-tools.ts` — call `registerMagicBlockTools` during
+  server initialization
+
+**Pricing:**
+
+| Tier | Price | Tools |
+|------|-------|-------|
+| READ | $0.01 | `getRoutes`, `getIdentity`, `getDelegationStatus`, `getAccountInfo`, `getBlockhashForAccounts`, `getSignatureStatuses`, `health`, `challenge`, `login`, `balance`, `privateBalance`, `swapQuote`, `isMintInitialized`, `getRandomnessResult` (14) |
+| WRITE | $0.05 | `deposit`, `transfer`, `withdraw`, `swap`, `initializeMint`, `requestRandomness` (6) |
+
+Every tool description includes its price ($0.01 or $0.05). Every
+successful response includes `priceUsd` and `priceBaseUnits` fields for
+SAP escrow settlement.
+
+**Validation:**
+
+- `tsc --noEmit` passed (0 errors).
+- `eslint` passed.
+- `vitest` 10/10 passed.
+
+## 0.6.0 - 2026-07-04
+
+### Highlights
+
+Introduces the SAP MCP Desktop Wizard: a guided GUI/TUI-style installer for non-technical users who need hosted SAP MCP, a local signer profile, and the x402 paid-call bridge configured without editing TOML or JSON by hand.
+
+### Added
+
+- Added a desktop Electron wizard under `apps/desktop` with an accessible aqua-themed setup flow for profile naming, wallet boundary, policy limits, runtime detection, and final review.
+- Added shared desktop setup core in `src/wizard-core/desktop-flow.ts` so the GUI persists the same production profile format as the CLI/TUI wizard instead of maintaining a separate installer path.
+- Added automatic Codex hosted MCP + local `sap_payments` bridge configuration from the desktop flow.
+- Added x402 paid-call addon installation from the desktop flow, writing runtime snippets under `~/.config/mcp-sap/addons/x402-paid-call`.
+- Added Electron Builder packaging config for macOS DMG/ZIP, Windows NSIS, and Linux tar.gz release artifacts.
+- Added macOS signing entitlements, notarization hook, and CI preflight for tagged release builds.
+- Added desktop wizard documentation in `apps/desktop/README.md`.
+- Added GitHub Actions desktop release workflow for native macOS, Windows, and Linux wizard artifacts on tagged releases or manual dispatch.
+
+### Changed
+
+- Bumped package metadata to `0.6.0`.
+- Added `react-dom`, Electron, Electron Builder, and Vite React tooling for the desktop installer surface.
+- Ignored generated desktop renderer and installer artifacts so release outputs are built intentionally and never committed as source.
+- Tagged macOS release jobs now report whether they are building signed/notarized or unsigned macOS artifacts.
+- Added a first-screen setup mode selector for full SAP MCP setup vs x402 payment-client-only repair, so users who already have `~/.config/mcp-sap` can install only the local payment bridge.
+- Expanded runtime-native config injection for Codex, Claude Desktop, Hermes global/profile configs, and OpenClaw instead of relying on one generic MCP JSON shape.
+- Added platform-aware Claude config paths for macOS, Windows, and Linux.
+- Improved Step 1 desktop wizard layout with a clearer hosted MCP/local trust-boundary explanation.
+- Added guarded desktop startup diagnostics so Windows users no longer get an infinite loading screen when preload/runtime detection fails; the wizard now times out with actionable fallback instructions and writes a desktop log.
+- Corrected OpenClaw hosted MCP and payment-bridge injection to use the documented `mcp.servers` configuration shape instead of a generic root `mcpServers` map.
+- Added hosted native wizard download metadata at `/wizard/downloads.json` and direct Windows, macOS, and Linux download cards on the public dashboard.
+- Published x402scan-compatible discovery metadata through `/.well-known/x402` and aligned the OpenAPI payment metadata with x402 resource discovery expectations.
+- Fixed the shared public server version constant so `/server.json`, `/openapi.json`, and release download links report `0.6.0` instead of stale metadata.
+- Hardened desktop release CI so Windows, macOS, and Linux jobs fail correctly when verification fails.
+- Added packaged `app.asar` verification to prevent blank renderer builds, absolute `/assets` paths, and missing Electron entrypoints from shipping.
+
+### Security
+
+- The desktop renderer never receives keypair bytes.
+- Hosted MCP config generated by the desktop flow contains only public remote endpoint metadata; local signing remains under `~/.config/mcp-sap` or an external signer.
+- The desktop flow rejects ambiguous `default` profile creation and requires named SAP MCP profiles.
+- Ad-hoc signed macOS artifacts are supported with explicit Gatekeeper/quarantine instructions; zero-warning macOS installers still require Developer ID signing and notarization.
+- Windows facilitator file-mode checks now skip POSIX-only chmod assertions while keeping Unix keypair mode enforcement intact.
+- Remote docs path resolution now uses POSIX URL normalization so Windows release runners do not produce platform-specific route mismatches.
+
+### Verification
+
+- `CI=true pnpm run typecheck`
+- `CI=true pnpm run test:run`
+- `CI=true pnpm run build`
+- `CI=true pnpm run desktop:renderer:build`
+- `CI=true pnpm run desktop:build`
+- `CI=true pnpm run desktop:verify-artifact`
+- `npm pack --dry-run --cache ./.npm-cache`
+- `pnpm audit --audit-level moderate`
+
+## 0.5.0 - 2026-07-03
+
+### Highlights
+
+First production-grade x402 monetized MCP server on Solana. This release delivers the full
+non-custodial payment flow — hosted server, client-side signing, facilitator verify+settle —
+with real MCP session management and a standalone client addon for AI agents.
+
+**Verified on-chain**: 5 successful USDC settlements on mainnet from wallet
+`28VEsvJpLodUaUReU6t2NFD2uWnqydi2vx2AMfa1HCQP` during testing.
+
+### Added
+
+- **x402 Payment-Signature fast path** (`src/payments/monetization-gate.ts`):
+  - Server parses `Payment-Signature` header (base64 JSON with `x402Version`, `accepted`,
+    `payload`, and `resource`), validates requirements against the original decision, and
+    calls facilitator `/verify` → execute tool → `/settle` in a single pass.
+  - 402 responses are returned as HTTP 200 JSON-RPC errors (`-32001 payment_required`) for
+    MCP SDK `streamable_http_client` compatibility (the SDK hangs for 55s on raw HTTP 402).
+  - `PAYMENT-REQUIRED` response header forwarded so client-side plugins can extract the
+    full x402 challenge including `accepts[]` with `extra.feePayer`.
+
+- **x402 V1/V2 compatibility** (`patchV1Compatibility()`):
+  - V2 `buildPaymentRequirements()` emits `amount` but no `maxAmountRequired`; V1 verifier
+    checks `maxAmountRequired`. The gate patches every 402/response body to add the alias,
+    so both V1 and V2 clients work without modification.
+
+- **Standalone x402 client addon** (`src/payments/x402-paid-call.ts`):
+  - New npm binary `sap-mcp-x402-paid-call` — initializes a real MCP session, receives the
+    x402 challenge, signs locally with the user's SAP profile keypair, and retries with
+    `Payment-Signature`.
+  - Local MCP tool `sap_x402_paid_call` (`src/tools/x402-paid-call-tool.ts`) — available
+    only when the process has a local wallet profile; not advertised by the non-custodial
+    hosted server.
+
+- **MCP session registry** (`src/remote/server.ts`):
+  - Replaced the global singleton `StreamableHTTPServerTransport` with a per-session
+    `Map<sessionId, transport>` architecture. Each client `initialize` creates a real
+    session; paid calls without a valid session are rejected before facilitator contact.
+  - Eliminates "Server already initialized" and "Session not found" errors that made the
+    hosted server unusable for multiple concurrent clients.
+
+- **Receipt binding to method + params** (`src/payments/usage-ledger.ts`):
+  - Payment receipts are now bound to the canonical MCP method-and-params hash, not the
+    raw JSON-RPC body including `id`. This lets agents retry with a different `id` without
+    invalidating the payment proof.
+
+- **Wizard addon flow** (`src/config/wizard.ts`, `src/config/mcp-client-injection.ts`):
+  - After client config, the wizard proposes optional installation of the `x402-paid-call`
+    addon into `~/.config/mcp-sap/addons/x402-paid-call`.
+  - Emits config snippets for Hermes, Claude Code, Codex, OpenClaw, and custom runtimes.
+
+- **Log rotation** (`scripts/setup-logrotate.sh`):
+  - PM2 logrotate config: 50MB max, 7 retained, compressed, daily rotation.
+
+- **x402 protocol spec** (`docs/x402-protocol-spec.md`):
+  - 984-line reference document covering V1/V2 schemas, header encoding, amount conversion,
+    facilitator endpoints, and Solana transaction structure.
+
+### Changed
+
+- Updated skills (`skills/sap-payments-x402/SKILL.md`, `skills/sap-mcp/SKILL.md`) to
+  document the `initialize → tools/call unpaid → tools/call paid retry` flow and the
+  non-custodial signing boundary.
+- Updated user docs (`USER_DOCS/03_PAYMENTS_X402_PAYSH.md`, `USER_DOCS/04_CLIENT_CONFIGS.md`)
+  to clarify that retries must preserve `mcp-session-id`, bind to `method + params`, and
+  must not fall back to free local stdio to bypass x402.
+- Updated landing page and wizard descriptor to surface `npx sap-mcp-x402-paid-call`.
+- Added explicit `/favicon.ico` compatibility metadata and route coverage for API-root browser previews.
+- Added crawler-safe `HEAD /favicon.ico` support and consolidated public logo handling for
+  `/favicon.ico`, `/favicon.png`, `/apple-touch-icon.png`, and `/og.png`.
+
+### Security
+
+- Keypair bytes are never printed, logged, or written to config files.
+- The non-custodial hosted server does not advertise `sap_x402_paid_call` when no wallet
+  is present — the tool only exists when a local signer is configured.
+- Paid calls with client-generated (fake) `mcp-session-id` values are rejected before
+  facilitator verification, preventing wasted on-chain settlements for doomed sessions.
+
+### Verification
+
+```
+CI=true pnpm run typecheck
+CI=true pnpm run lint
+CI=true pnpm run test:run        # 74 tests passed, 17 passed (suites)
+CI=true pnpm run build
+CI=true pnpm run verify:release
+node dist/payments/x402-paid-call.js --help
+npm pack --dry-run                # includes new binary
+```
+
+On-chain verification: 5/5 USDC settlements confirmed on Solana mainnet.
+
 ## 0.3.0 - 2026-07-02
 
 ### Fixed
@@ -14,12 +225,21 @@ All notable changes to this project are documented in this file.
 - Updated SAP MCP skills, prompts, and user docs to consistently reference the canonical hosted endpoint, public metadata routes, x402 fast path, and user-controlled signing boundary.
 - Clarified hosted non-custodial signing context so agents treat `signerConfigured: false` on the remote server as expected and do not silently fall back to local stdio to bypass x402.
 - Clarified CLI and TUI wizard mode selection so `hosted-api` is visibly the OOBE SAP MCP Server at `https://mcp.sap.oobeprotocol.ai/mcp`, not a prompt to run a local HTTP server.
+- Added explicit hosted-agent guidance to `sap_profile_current` and `sap://config/current` so clients do not summarize non-custodial hosted mode as "signer not configured", "read-only only", or "writes unavailable".
+- Fixed x402 signed retry handling by verifying the client-supplied `Payment-Signature.accepted` requirements instead of rebuilding requirements with a fresh facilitator fee payer.
+- Forwarded the `PAYMENT-REQUIRED` header on JSON-RPC `payment_required` responses so MCP clients can keep HTTP 200 compatibility while local payment plugins still receive the complete x402 challenge.
+- Bound x402 hosted receipts to the canonical MCP method-and-params hash instead of raw JSON-RPC bytes, preventing valid paid retries from failing when an agent changes only the JSON-RPC `id`.
+- Reworked hosted stateful MCP routing to create one official Streamable HTTP transport per initialized session instead of sharing a single global transport, and reject paid calls with missing or client-generated `mcp-session-id` before facilitator verification.
+- Added the local `sap-mcp-x402-paid-call` helper plus optional wizard-installed `x402_paid_call` addon snippets for Hermes, Claude, Codex, OpenClaw, and custom runtimes.
+- Added the local MCP helper tool `sap_x402_paid_call` for signed hosted x402 retries when a user-controlled SAP MCP wallet profile is present, while keeping the non-custodial hosted server from advertising it without a wallet.
+- Updated payment docs and skills so agents retry hosted paid calls with the same MCP method and params, preserve `mcp-session-id`, and do not fall back to free local stdio just because the hosted server has no signer.
+- Added `x402_paid_call` agent plugin install guidance and the `npx sap-mcp-x402-paid-call` command to the public hosted landing page and wizard descriptor.
 
 ### Verification
 
 - `pnpm run typecheck`
 - `pnpm run lint`
-- `pnpm run test:run -- src/config/mcp-client-injection.test.ts src/config/setup.test.ts src/payments/oobe-facilitator-server.test.ts src/payments/pricing.test.ts`
+- `pnpm test -- --run`
 - `pnpm run build`
 - `npm pack --dry-run --cache ./.npm-cache`
 
@@ -111,4 +331,4 @@ All notable changes to this project are documented in this file.
 - MCP client injection no longer pins wallet paths or RPC overrides by default.
 - Private key and transaction policy guards run before MCP tool execution/signing paths.
 - Payment audit logs store request hashes and settlement metadata, not keypair bytes, raw arguments, or x402 payment signatures.
-- Paid x402 virtual resource paths are bound to the SHA-256 hash of the exact JSON-RPC request body.
+- Paid x402 virtual resource paths are bound to the SHA-256 hash of canonical MCP method and params, so JSON-RPC `id` changes do not invalidate a valid paid retry.

package/README.md

@@ -100,6 +100,44 @@ For local agents, let SAP MCP follow the active profile manager instead of hard-
 }
 ```
 
+Codex uses TOML rather than the JSON `mcpServers` shape. For hosted remote MCP, add this to `~/.codex/config.toml` and restart Codex:
+
+```toml
+[mcp_servers.sap]
+url = "https://mcp.sap.oobeprotocol.ai/mcp"
+```
+
+For paid/write hosted tools, add the local non-custodial payment bridge as well:
+
+```toml
+[mcp_servers.sap_payments]
+command = "npx"
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"]
+enabled_tools = ["sap_x402_paid_call", "sap_profile_current", "sap_x402_estimate_cost"]
+tool_timeout_sec = 300
+
+[mcp_servers.sap_payments.env]
+SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
+SAP_ALLOWED_TOOLS = "sap_x402_paid_call,sap_profile_current,sap_x402_estimate_cost"
+SAP_LOG_LEVEL = "info"
+```
+
+On Windows, use `command = "npx.cmd"`. The wizard can write this automatically.
+
+Codex supports Streamable HTTP MCP servers with URL-based entries in `config.toml`. Use local stdio through `npx` only when you specifically want Codex to launch the local SAP MCP process:
+
+```toml
+[mcp_servers.sap]
+command = "npx"
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"]
+
+[mcp_servers.sap.env]
+SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
+SAP_LOG_LEVEL = "info"
+```
+
+On Windows, use `command = "npx.cmd"`.
+
 See [04. Local Stdio Usage](docs/04_LOCAL_STDIO_USAGE.md).
 
 ## 5. Remote Server
@@ -116,9 +154,14 @@ Remote endpoints:
 
 ```text
 GET     /
+GET     /docs
 GET     /server.json
 GET     /favicon.png
+GET     /favicon.ico
 GET     /health
+GET     /openapi.json
+GET     /.well-known/x402
+GET     /pay/provider.yml
 GET     /.well-known/agent-card.json
 GET     /.well-known/sap-mcp-wizard.json
 GET     /wizard/install.sh
@@ -129,6 +172,8 @@ DELETE  /mcp
 
 `GET /` is a public, share-safe landing page with Open Graph/Twitter metadata. It exposes only public server information; keypair bytes, private wallet paths, RPC query secrets, and VPS-local paths must never appear there.
 
+`GET /docs` serves the public documentation site for install, start, configuration, hosted remote MCP, x402/pay.sh payments, and MCP client setup.
+
 See [05. Remote VPS Deployment](docs/05_REMOTE_VPS_DEPLOYMENT.md) and [07. Endpoints And Clients](docs/07_ENDPOINTS_AND_CLIENTS.md).
 
 ## 6. Monetization
@@ -162,6 +207,9 @@ npx sap-mcp-facilitator start
 
 Generate a pay.sh provider YAML:
 
+The hosted public catalog is available at `https://mcp.sap.oobeprotocol.ai/pay/provider.yml`.
+It is secret-free and intended for pay.sh catalog/proxy discovery.
+
 ```bash
 npx sap-mcp-pay-sh-spec \
   --out sap-mcp-pay-sh.yml \
@@ -172,6 +220,20 @@ npx sap-mcp-pay-sh-spec \
 
 See [06. Payments, x402, And pay.sh](docs/06_PAYMENTS_X402_AND_PAYSH.md).
 
+For local agent runtimes that cannot replay x402 challenges natively, install
+the wizard's `x402_paid_call` addon or call the helper directly:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid-call \
+  --tool sap_list_all_agents \
+  --arguments '{"limit":5}' \
+  --max-usd 0.02 \
+  --confirm
+```
+
+The helper signs payment payloads with the user's local SAP MCP profile and
+never sends keypair bytes to the hosted server.
+
 ## 7. Commands
 
 ```bash
@@ -193,6 +255,7 @@ Installed binaries:
 | `sap-signing-proxy` | Local signing proxy |
 | `sap-mcp-facilitator` | Self-hosted x402 SVM facilitator |
 | `sap-mcp-pay-sh-spec` | pay.sh provider YAML generator |
+| `sap-mcp-x402-paid-call` | Local x402 payment helper for hosted paid MCP tools |
 
 ## 8. Documentation
 

package/USER_DOCS/00_START_HERE.md

@@ -21,6 +21,14 @@ Run the wizard:
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
 ```
 
+For non-technical users, download the Desktop GUI Wizard from GitHub releases:
+
+```txt
+https://github.com/OOBE-PROTOCOL/sap-mcp/releases
+```
+
+The Desktop GUI Wizard creates the same profile and signer setup as the CLI wizard, then can configure hosted MCP plus the local x402 payment bridge for supported agent runtimes.
+
 Show the active profile:
 
 ```bash
@@ -33,6 +41,12 @@ Hosted MCP URL:
 https://mcp.sap.oobeprotocol.ai/mcp
 ```
 
+Hosted documentation:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/docs
+```
+
 Wizard descriptor:
 
 ```txt
@@ -82,7 +96,14 @@ Minimal hosted MCP client concept:
 }
 ```
 
-If a client does not support remote Streamable HTTP MCP yet, use local stdio mode and let the local server connect to the same SAP/Solana stack.
+Codex users should not paste that JSON into `~/.codex/config.toml`. Use TOML:
+
+```toml
+[mcp_servers.sap]
+url = "https://mcp.sap.oobeprotocol.ai/mcp"
+```
+
+Codex supports Streamable HTTP MCP servers with URL-based TOML entries. Use local stdio mode only when you want Codex to launch the SAP MCP process locally.
 
 ## 5. Safety Rules For Agents
 
@@ -128,3 +149,4 @@ npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config au
 | `03_PAYMENTS_X402_PAYSH.md` | x402, pay.sh pay-per-use, and pay.sh subscriptions |
 | `04_CLIENT_CONFIGS.md` | Claude, Hermes, Codex, OpenClaw config examples |
 | `05_SKILLS_AND_TOOLS.md` | Skills, tool selection, and security behavior |
+| `06_DESKTOP_GUI_WIZARD.md` | Desktop GUI wizard install, hosted setup, x402 client addon, and runtime behavior |

package/USER_DOCS/01_HOSTED_REMOTE_MCP.md

@@ -44,7 +44,8 @@ Public `server.json` shape:
     "agentCard": "https://mcp.sap.oobeprotocol.ai/.well-known/agent-card.json",
     "wizardDescriptor": "https://mcp.sap.oobeprotocol.ai/.well-known/sap-mcp-wizard.json",
     "wizardInstallScript": "https://mcp.sap.oobeprotocol.ai/wizard/install.sh",
-    "favicon": "https://mcp.sap.oobeprotocol.ai/favicon.png"
+    "favicon": "https://mcp.sap.oobeprotocol.ai/favicon.png",
+    "faviconIco": "https://mcp.sap.oobeprotocol.ai/favicon.ico"
   },
   "capabilities": {
     "tools": true,
@@ -88,6 +89,8 @@ Read-only discovery can connect directly to the hosted MCP URL. Any agent that n
 
 If `sap_profile_current` reports `runtime.signerConfigured: false` on the hosted server, read it as a non-custodial guarantee: OOBE is not holding the user's wallet. It is not a reason to switch to local stdio automatically. Paid hosted tools should complete the x402/pay.sh payment flow from the user's local SAP profile or external signer. Use local stdio only when the user explicitly chooses local execution or the client cannot support remote Streamable HTTP/x402.
 
+Agent-facing summary should say: "Hosted SAP MCP is connected. OOBE is non-custodial; user signatures come from the local SAP profile or external signer." Avoid "signer not configured", "read-only only", or "writes unavailable" unless a specific tool call returns that exact error.
+
 ## 3. Install And Configure
 
 ```bash

package/USER_DOCS/03_PAYMENTS_X402_PAYSH.md

@@ -42,7 +42,7 @@ Without payment, a paid tool returns:
 HTTP/1.1 402 Payment Required
 ```
 
-The response contains payment instructions and the caller replays the same request with the payment header.
+The response contains payment instructions and the caller retries the same MCP method and params with the payment header. Agents must keep the initialized MCP session headers across both the unpaid challenge and the paid retry.
 
 Hosted SAP MCP accepts payment proof headers used by the x402/payment flow and exposes settlement headers back to the caller:
 
@@ -52,12 +52,66 @@ Hosted SAP MCP accepts payment proof headers used by the x402/payment flow and e
 | Server challenge | `PAYMENT-REQUIRED` |
 | Server receipt | `PAYMENT-RESPONSE` or `X-PAYMENT-RESPONSE` |
 
-The payment receipt should be treated as part of the tool output provenance. For paid hosted tools, agents should bind the receipt to the request hash, tool name, and returned result.
+The payment receipt should be treated as part of the tool output provenance. For paid hosted tools, agents should bind the receipt to the canonical request hash, tool name, method params, and returned result. The canonical hash ignores JSON-RPC `id`, so normal agent retries do not invalidate the receipt.
 
-## 3. pay.sh Pay-Per-Use
+## 3. Local x402 Paid-Call Addon
+
+Most agent runtimes can connect to hosted SAP MCP directly, but not every runtime can automatically sign an x402 challenge and replay the paid MCP request. SAP MCP ships a local helper for that gap:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid-call \
+  --tool sap_list_all_agents \
+  --arguments '{"limit":5}' \
+  --max-usd 0.02 \
+  --max-attempts 5 \
+  --confirm
+```
+
+The helper:
+
+1. loads the user's active SAP MCP profile from `~/.config/mcp-sap`;
+2. initializes a real MCP session against `https://mcp.sap.oobeprotocol.ai/mcp`;
+3. receives the x402 challenge for the requested hosted tool;
+4. signs the payment payload locally with the user's SAP MCP profile wallet;
+5. retries the same MCP method and params with `PAYMENT-SIGNATURE`;
+6. returns the hosted MCP response plus the settlement receipt.
+
+Install or print addon snippets from the wizard:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+```
+
+The wizard writes the addon bundle under:
+
+```txt
+~/.config/mcp-sap/addons/x402-paid-call
+```
+
+Local stdio SAP MCP also exposes `sap_x402_paid_call` when the current process has a user-controlled wallet profile. The OOBE hosted server does not advertise this helper in non-custodial mode because payment signing must happen on the user's machine, not on `mcp.sap.oobeprotocol.ai`.
+
+Security boundaries:
+
+- keypair bytes stay local and are never included in MCP client config;
+- every paid call requires `--max-usd` / `maxPriceUsd`;
+- every paid call requires `--confirm` / `confirm: true`;
+- transient settlement failures such as `BlockhashNotFound`,
+  `transaction_simulation_failed`, `node is behind`, or `fetch failed` should
+  be retried with a fresh challenge using `--max-attempts 5`;
+- encrypted wallet and external signer bridges are not faked; unsupported signing modes fail closed.
+
+## 4. pay.sh Pay-Per-Use
 
 pay.sh pay-per-use uses a provider YAML with `metering:` on paid endpoints. The pay.sh docs describe this as stablecoin-gated HTTP where the first request receives a `402`, the client signs proof locally, and the gateway settles before forwarding upstream.
 
+The hosted SAP MCP deployment publishes the public pay.sh catalog here:
+
+```text
+https://mcp.sap.oobeprotocol.ai/pay/provider.yml
+```
+
+That hosted YAML is safe to share. It contains the provider name, proxy routing target, network, revenue recipient, and metered `/mcp` endpoint, but not RPC API keys, signer paths, facilitator auth tokens, or wallet bytes.
+
 References:
 
 - https://pay.sh/docs/building-with-pay/getting-started
@@ -74,6 +128,8 @@ npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-pay-sh-sp
   --recipient <OOBE_REVENUE_WALLET>
 ```
 
+Only publish YAML generated this way if it does not include private `--rpc-url` or `--signer-path` values.
+
 Example metered block:
 
 ```yaml
@@ -112,7 +168,7 @@ operator:
   recipient: '<OOBE_REVENUE_WALLET>'
 ```
 
-## 4. pay.sh Subscriptions
+## 5. pay.sh Subscriptions
 
 pay.sh subscriptions use `subscription:` instead of `metering:`. A subscription gates an endpoint behind recurring flat-fee access for a fixed period. According to pay.sh docs, `metering:` and `subscription:` are mutually exclusive on the same endpoint, so use separate endpoints or separate provider specs when offering both.
 
@@ -184,7 +240,7 @@ pay subscriptions list --network mainnet
 pay subscriptions list --json
 ```
 
-## 5. Recommended OOBE Product Split
+## 6. Recommended OOBE Product Split
 
 | Product | Payment Model |
 | --- | --- |
@@ -194,7 +250,7 @@ pay subscriptions list --json
 | Pro remote access | pay.sh subscription endpoint |
 | Enterprise/custom routing | Dedicated subscription endpoint or private contract |
 
-## 6. Official pay.sh References Used
+## 7. Official pay.sh References Used
 
 - Getting started: https://pay.sh/docs/building-with-pay/getting-started
 - Pricing: https://pay.sh/docs/building-with-pay/pricing
@@ -203,7 +259,7 @@ pay subscriptions list --json
 - Subscriptions YAML specification: https://pay.sh/docs/building-with-pay/subscriptions/yaml-specification
 - Subscription examples: https://pay.sh/docs/building-with-pay/subscriptions/examples
 
-## 7. Security Requirements
+## 8. Security Requirements
 
 - Never put RPC API keys in public YAML.
 - Never put private keypair paths in public docs.