@oobe-protocol-labs/sap-mcp-server 0.7.3 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,145 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
+### Added
+
+- Added homepage and docs quick-start steppers for the two supported integration
+  paths: native desktop download for normal users and CLI wizard for developers,
+  with direct references to `/docs` pages for desktop setup, client configs, and
+  x402/pay.sh payments.
+- Redesigned the hosted landing page navigation and integration path as a
+  server-rendered glass navigation bar plus shadcn-inspired setup cards with
+  native Windows, macOS, and Linux download actions.
+
+### Fixed
+
+- Fixed the packaged Windows desktop wizard startup by converting the internal
+  `dist/wizard-core` module path to a `file://` URL before dynamic ESM import.
+  This prevents `ERR_UNSUPPORTED_ESM_URL_SCHEME` when the app is installed under
+  a `C:\...` path.
+- Fixed desktop wizard responsiveness on narrower macOS and Windows windows by
+  removing page-level horizontal overflow, collapsing the setup chooser before
+  it clips, and constraining long paths/URLs inside cards.
+- Added a persistent Home action to the desktop wizard sidebar so users can
+  return to the initial setup choice after finishing a repair or full setup.
+- Fixed landing page setup-step layout on desktop and mobile by moving long CLI
+  commands out of numbered steps, making command blocks horizontally scrollable,
+  and preventing equal-height cards from stretching the stepper content.
+- Refined the public install and native download cards so the release badge,
+  platform cards, and direct installer links clearly target the current 0.8.0
+  desktop wizard assets.
+- Added the missing OpenAPI description for generic JSON-RPC `params` so
+  x402/pay.sh catalog validators and agent indexers can explain every required
+  request-body field.
+- Removed MagicBlock `mock` authentication switches from public MCP tool schemas
+  and request forwarding so production tools expose only real API flows.
+- Made hosted `sap` plus local `sap_payments` runtime injection platform-aware
+  end to end, with Windows tests proving that Codex, Claude, Hermes, and
+  OpenClaw payment bridge configs use `npx.cmd` where required.
+
+## 0.8.0 - 2026-07-14
+
+### Changed
+
+- Made the normal wizard path hosted-first: `hosted-api` is now the default
+  recommended mode because agents should connect to
+  `https://mcp.sap.oobeprotocol.ai/mcp` while signatures and x402 proofs stay
+  local through the user SAP MCP profile.
+- Promoted the native `sap_payments` MCP bridge from an optional add-on style
+  step to the recommended hosted paid/write setup for Claude, Hermes, Codex,
+  OpenClaw, and compatible runtimes.
+- Updated the desktop wizard default draft to use hosted SAP MCP plus local
+  signing, added clearer normie-friendly setup copy, and added runtime actions
+  for selecting detected or all supported agent runtimes.
+- Updated README and user docs to describe the recommended two-entry runtime
+  configuration: hosted `sap` plus local non-custodial `sap_payments`.
+
+### Verification
+
+- `CI=true pnpm run typecheck`
+- `CI=true pnpm test -- --run src/payments/pricing.test.ts src/server/create-server.test.ts src/config/mcp-client-injection.test.ts src/wizard-core/desktop-flow.test.ts`
+- `CI=true pnpm run lint`
+- `CI=true pnpm run build`
+- `CI=true pnpm run desktop:renderer:build`
+
+## 0.7.7 - 2026-07-14
+
+### Changed
+
+- Updated hosted profile tools to report the remote server as an explicit
+  accountless, non-custodial gateway instead of exposing a misleading
+  `default` profile from the VPS runtime.
+- Added agent-facing guidance that local user profile, wallet, and signer
+  status must be read through the local `sap_payments.sap_profile_current`
+  bridge when the caller is connected to hosted remote MCP.
+- Moved basic wallet balance reads (`sol_get_balance`,
+  `spl-token_getBalance`, and `spl-token_getTokenAccounts`) into the free
+  hosted tier so balance checks no longer depend on x402 facilitator
+  settlement or blockhash simulation.
+
+### Verification
+
+- `CI=true pnpm run typecheck`
+- `CI=true pnpm test -- --run src/payments/pricing.test.ts`
+
+## 0.7.6 - 2026-07-14
+
+### Changed
+
+- Renamed desktop wizard and CLI wizard language from separate x402
+  plugin/addon setup to the native local SAP MCP `sap_payments` bridge.
+- Updated user docs, runtime snippets, and skills to make
+  `sap_payments_call_paid_tool` the default hosted paid-tool path, with the
+  standalone `sap-mcp-x402-paid-call` command documented only as a legacy
+  terminal/custom-wrapper fallback.
+- Prepared desktop release automation for signed macOS and Windows artifacts by
+  selecting OS-specific certificate secrets and publishing `SHA256SUMS.txt`
+  alongside DMG/ZIP/EXE/tar.gz outputs.
+
+### Verification
+
+- `CI=true pnpm run verify:release`
+
+## 0.7.5 - 2026-07-14
+
+### Added
+
+- Added native SAP MCP x402 challenge tools for agent runtimes:
+  `sap_payments_call_paid_tool`, `sap_payments_prepare_challenge`,
+  `sap_payments_sign_challenge`, and `sap_payments_verify_receipt`.
+- Kept `sap_x402_paid_call` as a backward-compatible alias while making
+  `sap_payments_call_paid_tool` the recommended high-level path for hosted
+  paid/write tool calls.
+- Added local receipt inspection coverage for `PAYMENT-RESPONSE` and
+  `X-PAYMENT-RESPONSE` headers.
+
+### Changed
+
+- Updated runtime injection snippets so the local `sap_payments` bridge exposes
+  the complete payment challenge toolchain instead of only the legacy helper.
+- Updated SAP MCP skills, prompts, and payment docs to teach agents the native
+  x402 challenge flow and avoid terminal/direct-RPC bypasses.
+
+### Verification
+
+- `CI=true pnpm run verify:release`
+
+## 0.7.4 - 2026-07-13
+
+### Changed
+
+- Added top-level metadata aliases to `/server.json` and
+  `/.well-known/mcp/server-card.json` for registry crawlers that score
+  description, homepage, icon, and display name outside nested MCP
+  `serverInfo` fields.
+- Kept all metadata values derived from the canonical hosted SAP MCP title,
+  public description, homepage, and favicon without adding synthetic registry
+  data.
+
+### Verification
+
+- `CI=true pnpm run verify:release`
+
 ## 0.7.3 - 2026-07-13
 
 ### Added

package/README.md

@@ -80,7 +80,12 @@ or from source:
 node dist/cli.js
 ```
 
-Hosted customers connect their agents to `https://mcp.sap.oobeprotocol.ai/mcp`, but signing remains user-controlled. Any user who wants to pay x402/pay.sh charges, register or operate a SAP identity, or execute value-moving Solana/SAP tools should run the wizard first and keep the dedicated wallet under `~/.config/mcp-sap/keypairs/` or behind an external signer. Read-only hosted discovery can use the remote URL without a local signer.
+Hosted customers connect their agents to `https://mcp.sap.oobeprotocol.ai/mcp`, but signing remains user-controlled. The recommended setup for most users is the wizard-managed pair of MCP entries:
+
+- `sap`: hosted Streamable HTTP SAP MCP at `https://mcp.sap.oobeprotocol.ai/mcp`;
+- `sap_payments`: local non-custodial payment bridge for x402/pay.sh paid/write calls.
+
+Any user who wants to pay x402/pay.sh charges, register or operate a SAP identity, or execute value-moving Solana/SAP tools should run the wizard first and keep the dedicated wallet under `~/.config/mcp-sap/keypairs/` or behind an external signer. Read-only hosted discovery can use the remote URL without a local signer.
 
 ## 4. Local Client Config
 
@@ -112,13 +117,14 @@ 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"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"]
+startup_timeout_sec = 300
 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_MCP_PAYMENTS_BRIDGE_ONLY = "true"
+SAP_ALLOWED_TOOLS = "all"
 SAP_LOG_LEVEL = "info"
 ```
 
@@ -129,7 +135,7 @@ Codex supports Streamable HTTP MCP servers with URL-based entries in `config.tom
 ```toml
 [mcp_servers.sap]
 command = "npx"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"]
 
 [mcp_servers.sap.env]
 SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
@@ -221,7 +227,8 @@ 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:
+the wizard's local `sap_payments` bridge and call `sap_payments_call_paid_tool`.
+The legacy CLI helper is still available for terminal use:
 
 ```bash
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid-call \
@@ -255,7 +262,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 |
+| `sap-mcp-x402-paid-call` | Legacy terminal/custom-wrapper fallback for hosted x402 paid MCP tools |
 
 ## 8. Documentation
 

package/USER_DOCS/00_START_HERE.md

@@ -15,19 +15,45 @@ Use one of two deployment modes:
 
 Hosted MCP still requires a local SAP MCP profile when the agent needs to sign payments or value-moving transactions. The hosted server never receives keypair bytes. The user's machine or external signer owns the trust boundary.
 
-Run the wizard:
+Choose one setup path:
 
-```bash
-npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
-```
+| Path | Best For | What It Does |
+| --- | --- | --- |
+| Native Desktop Wizard | Non-technical users and first-time setup | Downloads a guided GUI, creates the local SAP profile, detects runtimes, and configures hosted `sap` plus local `sap_payments`. |
+| CLI Wizard | Developers, terminal users, servers | Runs the same setup from npm and can print or inject runtime config. |
+
+### Native Desktop Wizard
+
+1. Download the wizard from GitHub releases or from the hosted downloads descriptor.
+2. Open the wizard and choose **Full hosted SAP MCP setup**.
+3. Select detected runtimes such as Codex, Claude, Hermes, or OpenClaw.
+4. Restart the agent runtime and connect to hosted SAP MCP.
 
-For non-technical users, download the Desktop GUI Wizard from GitHub releases:
+Release downloads:
 
 ```txt
 https://github.com/OOBE-PROTOCOL/sap-mcp/releases
+https://mcp.sap.oobeprotocol.ai/wizard/downloads.json
+```
+
+More details:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/docs/#/user/06_DESKTOP_GUI_WIZARD
+```
+
+### CLI Wizard
+
+Run the wizard:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
 ```
 
-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.
+1. Accept the default **hosted-api** mode for hosted SAP MCP.
+2. Create or import the dedicated local SAP MCP wallet profile.
+3. Let the wizard configure hosted `sap` plus local `sap_payments` for supported runtimes.
+4. Use `sap_payments_call_paid_tool` when a hosted tool requires x402 payment.
 
 Show the active profile:
 
@@ -47,6 +73,18 @@ Hosted documentation:
 https://mcp.sap.oobeprotocol.ai/docs
 ```
 
+Client config docs:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/docs/#/user/04_CLIENT_CONFIGS
+```
+
+Payment docs:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/docs/#/user/03_PAYMENTS_X402_PAYSH
+```
+
 Wizard descriptor:
 
 ```txt
@@ -149,4 +187,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 |
+| `06_DESKTOP_GUI_WIZARD.md` | Desktop GUI wizard install, hosted setup, local payment bridge, and runtime behavior |

package/USER_DOCS/01_HOSTED_REMOTE_MCP.md

@@ -89,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.
 
+Hosted remote is accountless. If `sap_profile_current` returns `accountModel: hosted-remote-accountless`, the hosted server cannot see the user's local `~/.config/mcp-sap` profile and should not be summarized as profile `default`. Use the local `sap_payments.sap_payments_profile_current` bridge to inspect the user's real profile, wallet, and signer status.
+
 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

package/USER_DOCS/03_PAYMENTS_X402_PAYSH.md

@@ -54,9 +54,15 @@ Hosted SAP MCP accepts payment proof headers used by the x402/payment flow and e
 
 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. Local x402 Paid-Call Addon
+## 3. Local SAP MCP Payment Bridge
 
-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:
+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. The recommended fix is the local `sap_payments` MCP bridge created by the wizard. Agents should call:
+
+```txt
+sap_payments_call_paid_tool
+```
+
+The standalone CLI helper remains available as a terminal/custom-wrapper fallback:
 
 ```bash
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid-call \
@@ -76,19 +82,21 @@ The helper:
 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:
+Install or repair runtime bridge config 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:
+The wizard can also write a local reference 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`.
+Local stdio SAP MCP also exposes the `sap_payments_call_paid_tool` challenge bridge and the legacy `sap_x402_paid_call` alias when the current process has a user-controlled wallet profile. The OOBE hosted server does not advertise these local signing helpers in non-custodial mode because payment signing must happen on the user's machine, not on `mcp.sap.oobeprotocol.ai`.
+
+Basic wallet reads do not require x402. Call `sol_get_balance`, `spl-token_getBalance`, and `spl-token_getTokenAccounts` directly on hosted SAP MCP. They should not be routed through the local payment bridge and should not depend on the facilitator.
 
 Security boundaries:
 

package/USER_DOCS/04_CLIENT_CONFIGS.md

@@ -45,13 +45,14 @@ url = "https://mcp.sap.oobeprotocol.ai/mcp"
 
 [mcp_servers.sap_payments]
 command = "npx.cmd"
-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"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"]
+startup_timeout_sec = 300
 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_MCP_PAYMENTS_BRIDGE_ONLY = "true"
+SAP_ALLOWED_TOOLS = "all"
 SAP_LOG_LEVEL = "info"
 ```
 
@@ -64,7 +65,7 @@ the complete local stdio SAP MCP process instead of using the hosted endpoint, u
 ```toml
 [mcp_servers.sap]
 command = "npx.cmd"
-args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"]
 
 [mcp_servers.sap.env]
 SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
@@ -110,6 +111,7 @@ Use this when the client requires stdio:
       "cwd": "/absolute/path/to/sap-mcp-server",
       "env": {
         "SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE": "false",
+        "SAP_MCP_PAYMENTS_BRIDGE_ONLY": "true",
         "SAP_LOG_LEVEL": "info"
       }
     }
@@ -128,6 +130,7 @@ mcp_servers:
     cwd: /absolute/path/to/sap-mcp-server
     env:
       SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE: "false"
+      SAP_MCP_PAYMENTS_BRIDGE_ONLY: "true"
       SAP_LOG_LEVEL: info
 ```
 
@@ -141,6 +144,7 @@ cwd = "/absolute/path/to/sap-mcp-server"
 
 [mcp_servers.sap.env]
 SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE = "false"
+SAP_MCP_PAYMENTS_BRIDGE_ONLY = "true"
 SAP_LOG_LEVEL = "info"
 ```
 
@@ -154,15 +158,15 @@ Run:
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
 ```
 
-## 8. x402 Paid-Call Addon
+## 8. Local SAP MCP Payment Bridge
 
-Hosted SAP MCP paid tools return an x402 challenge. Some agent runtimes expose remote MCP tools but do not yet have a native x402 replay path. The wizard can install a local addon bundle for Hermes, Claude, Codex, OpenClaw, or custom runtimes:
+Hosted SAP MCP paid tools return an x402 challenge. Some agent runtimes expose remote MCP tools but do not yet have a native x402 replay path. The wizard configures a local `sap_payments` MCP bridge for Hermes, Claude, Codex, OpenClaw, or custom runtimes. It can also install a reference bundle for repair/custom clients:
 
 ```txt
 ~/.config/mcp-sap/addons/x402-paid-call
 ```
 
-The addon command is:
+Normal agents should call `sap_payments_call_paid_tool` through the local `sap_payments` bridge. The standalone command is a terminal/custom-wrapper fallback:
 
 ```bash
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid-call \
@@ -176,6 +180,10 @@ For Codex, the recommended runtime integration is the local `sap_payments` MCP
 bridge shown above. It exposes only:
 
 ```txt
+sap_payments_call_paid_tool
+sap_payments_prepare_challenge
+sap_payments_sign_challenge
+sap_payments_verify_receipt
 sap_x402_paid_call
 sap_profile_current
 sap_x402_estimate_cost
@@ -185,14 +193,16 @@ For Claude Code, use the official MCP CLI pattern:
 
 ```bash
 claude mcp add --transport http sap https://mcp.sap.oobeprotocol.ai/mcp
-claude mcp add --transport stdio sap_payments -- npx --yes --package @oobe-protocol-labs/sap-mcp-server sap-mcp-server
+claude mcp add --transport stdio sap_payments -- npx --yes --package @oobe-protocol-labs/sap-mcp-server@0.8.0 sap-mcp-server
 ```
 
-Set `SAP_ALLOWED_TOOLS=sap_x402_paid_call,sap_profile_current,sap_x402_estimate_cost`
-in the local bridge environment if your Claude runtime exposes environment
-configuration. This keeps the local bridge focused on payment retries.
+Set `SAP_MCP_PAYMENTS_BRIDGE_ONLY=true` and `SAP_ALLOWED_TOOLS=all` in the
+local bridge environment if your Claude runtime exposes environment
+configuration. The bridge-only flag keeps the local process focused on payment
+retries while `all` prevents future payment helper tools from being hidden by a
+stale allow-list.
 
-Hermes plugin/addon concept:
+Legacy Hermes command-wrapper concept:
 
 ```json
 {
@@ -209,11 +219,11 @@ Hermes plugin/addon concept:
 }
 ```
 
-Local MCP tool alternative:
+Preferred local MCP tool call:
 
 ```json
 {
-  "name": "sap_x402_paid_call",
+  "name": "sap_payments_call_paid_tool",
   "arguments": {
     "toolName": "sap_list_all_agents",
     "arguments": { "limit": 5 },
@@ -223,4 +233,4 @@ Local MCP tool alternative:
 }
 ```
 
-Do not add wallet paths, keypair bytes, RPC API keys, or profile-specific overrides to hosted MCP client config. Hosted MCP config points to `https://mcp.sap.oobeprotocol.ai/mcp`; the local addon/profile signs only the payment payload on the user's machine.
+Do not add wallet paths, keypair bytes, RPC API keys, or profile-specific overrides to hosted MCP client config. Hosted MCP config points to `https://mcp.sap.oobeprotocol.ai/mcp`; the local `sap_payments` bridge signs only the payment payload on the user's machine.

package/USER_DOCS/06_DESKTOP_GUI_WIZARD.md

@@ -10,7 +10,7 @@ It creates the same real SAP MCP profile as the CLI/TUI wizard:
 - a dedicated local SAP MCP wallet or external signer boundary;
 - conservative policy limits;
 - hosted MCP config for `https://mcp.sap.oobeprotocol.ai/mcp`;
-- optional local x402 paid-call bridge for agent runtimes.
+- native local `sap_payments` bridge for hosted paid/write agent calls.
 
 The desktop app is not a mock installer. It calls the same setup modules used by `sap-mcp-config wizard`.
 
@@ -18,8 +18,15 @@ The first screen lets you choose one of two modes:
 
 | Mode | Use It When |
 | --- | --- |
-| **Full SAP MCP setup** | You are creating or refreshing a SAP MCP profile, wallet boundary, policy limits, hosted MCP entry, and x402 payment bridge. |
-| **Install x402 payment client only** | You already have `~/.config/mcp-sap` configured, hosted tools are visible, but paid/write calls still return `payment_required`. |
+| **Full hosted SAP MCP setup** | **Recommended.** You are creating or refreshing a SAP MCP profile, wallet boundary, policy limits, hosted MCP entry, and native local payment bridge. |
+| **Payment bridge repair** | You already have `~/.config/mcp-sap` configured, hosted tools are visible, but paid/write calls still return `payment_required`. |
+
+The default full setup path configures two MCP entries for supported runtimes:
+
+- `sap`: the hosted Streamable HTTP server at `https://mcp.sap.oobeprotocol.ai/mcp`;
+- `sap_payments`: a local stdio bridge that signs x402 payment proofs with the user's SAP MCP profile or external signer.
+
+This is the normal path for non-technical users and the recommended production path for technical users. Local stdio-only SAP MCP is still available for development, but it is not the default hosted onboarding flow.
 
 ## 2. When To Use It
 
@@ -71,14 +78,14 @@ Do not paste wallet/keypair material into support chats while troubleshooting in
 
 The desktop wizard walks through:
 
-1. **Setup**: choose full setup or x402 payment-client-only repair.
+1. **Setup**: choose recommended full hosted setup or payment bridge repair.
 2. **Profile**: choose a real profile name; the wizard refuses ambiguous `default` profiles.
 3. **Wallet**: create a dedicated SAP MCP wallet or point to an existing dedicated keypair path.
 4. **Policy**: set max transaction value, daily limits, log level, and optional Bento Guard settings.
-5. **Runtimes**: detect local agent runtimes and configure hosted SAP MCP plus local `sap_payments`.
+5. **Runtimes**: detect local agent runtimes and configure hosted SAP MCP plus local `sap_payments` using native JSON, TOML, or YAML for each runtime.
 6. **Review**: show config path, wallet boundary, hosted MCP endpoint, and runtime actions before writing.
 
-In x402 payment-client-only mode, the wizard skips profile, wallet, and policy steps. It only installs or repairs runtime MCP client entries and the optional addon bundle.
+In payment bridge repair mode, the wizard skips profile, wallet, and policy steps. It only installs or repairs runtime MCP client entries and the optional local payment bridge reference bundle.
 
 The renderer never receives keypair bytes. Wallet creation and file writes happen in the local main process.
 
@@ -92,13 +99,14 @@ url = "https://mcp.sap.oobeprotocol.ai/mcp"
 
 [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"]
+args = ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"]
+startup_timeout_sec = 300
 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_MCP_PAYMENTS_BRIDGE_ONLY = "true"
+SAP_ALLOWED_TOOLS = "all"
 SAP_LOG_LEVEL = "info"
 ```
 
@@ -123,10 +131,11 @@ Claude Desktop uses a root `mcpServers` JSON object:
     },
     "sap_payments": {
       "command": "npx",
-      "args": ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"],
+      "args": ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"],
       "env": {
         "SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE": "false",
-        "SAP_ALLOWED_TOOLS": "sap_x402_paid_call,sap_profile_current,sap_x402_estimate_cost",
+        "SAP_MCP_PAYMENTS_BRIDGE_ONLY": "true",
+        "SAP_ALLOWED_TOOLS": "all",
         "SAP_LOG_LEVEL": "info"
       }
     }
@@ -154,10 +163,11 @@ Hermes global `mcp.json` uses flat server entries:
   },
   "sap_payments": {
     "command": "npx",
-    "args": ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"],
+    "args": ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"],
     "env": {
       "SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE": "false",
-      "SAP_ALLOWED_TOOLS": "sap_x402_paid_call,sap_profile_current,sap_x402_estimate_cost",
+      "SAP_MCP_PAYMENTS_BRIDGE_ONLY": "true",
+      "SAP_ALLOWED_TOOLS": "all",
       "SAP_LOG_LEVEL": "info"
     }
   }
@@ -176,11 +186,12 @@ mcp_servers:
     args:
       - --yes
       - --package
-      - @oobe-protocol-labs/sap-mcp-server
+      - @oobe-protocol-labs/sap-mcp-server@0.8.0
       - sap-mcp-server
     env:
       SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE: "false"
-      SAP_ALLOWED_TOOLS: sap_x402_paid_call,sap_profile_current,sap_x402_estimate_cost
+      SAP_MCP_PAYMENTS_BRIDGE_ONLY: "true"
+      SAP_ALLOWED_TOOLS: all
       SAP_LOG_LEVEL: info
 ```
 
@@ -197,10 +208,11 @@ OpenClaw MCP JSON uses the same root `mcpServers` structure as generic MCP clien
     },
     "sap_payments": {
       "command": "npx",
-      "args": ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server", "sap-mcp-server"],
+      "args": ["--yes", "--package", "@oobe-protocol-labs/sap-mcp-server@0.8.0", "sap-mcp-server"],
       "env": {
         "SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE": "false",
-        "SAP_ALLOWED_TOOLS": "sap_x402_paid_call,sap_profile_current,sap_x402_estimate_cost",
+        "SAP_MCP_PAYMENTS_BRIDGE_ONLY": "true",
+        "SAP_ALLOWED_TOOLS": "all",
         "SAP_LOG_LEVEL": "info"
       }
     }
@@ -210,15 +222,17 @@ OpenClaw MCP JSON uses the same root `mcpServers` structure as generic MCP clien
 
 On Windows, command-backed bridge entries use `npx.cmd`.
 
-## 7. x402 Client Addon
+## 7. Local Payment Bridge Reference Bundle
 
-The GUI can also install the x402 addon bundle under:
+The GUI can also install a local bridge reference bundle under:
 
 ```txt
 ~/.config/mcp-sap/addons/x402-paid-call
 ```
 
-Direct helper command:
+Normal agents should use the local `sap_payments` MCP bridge and call
+`sap_payments_call_paid_tool`. The standalone command remains available only as
+a terminal/custom-wrapper fallback:
 
 ```bash
 npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid-call \
@@ -228,7 +242,8 @@ npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-x402-paid
   --confirm
 ```
 
-Use the helper when your agent runtime can see hosted tools but cannot natively sign and replay x402 challenges.
+Use the command fallback only when your runtime cannot add the local
+`sap_payments` MCP bridge.
 
 ## 8. CLI Fallback
 

package/assets/logos/drift.svg

@@ -0,0 +1,12 @@
+<svg width="256" height="256" viewBox="0 0 256 256" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M0 64C0 28.6538 28.6538 0 64 0H192C227.346 0 256 28.6538 256 64V192C256 227.346 227.346 256 192 256H64C28.6538 256 0 227.346 0 192V64Z" fill="#08AA18"/>
+<g clip-path="url(#clip0_354_3823)">
+<path d="M32 62.9677C32 45.8647 45.8647 32 62.9677 32H193.032C210.135 32 224 45.8647 224 62.9677V193.032C224 210.135 210.135 224 193.032 224H62.9677C45.8647 224 32 210.135 32 193.032V62.9677Z" fill="#08AA18"/>
+<path d="M105.764 71.4325C105.367 72.4792 106.14 73.599 107.259 73.5993H129.162C130.199 73.5993 130.962 74.5712 130.717 75.5786L116.825 132.535C116.424 134.18 118.518 135.239 119.606 133.941L169.692 74.1724C169.996 73.8097 170.446 73.5993 170.919 73.5993H203.043C204.411 73.5993 205.148 75.2066 204.256 76.2439L77.1854 224H65.261L92.329 110.773C92.5694 109.767 91.8069 108.8 90.7731 108.799H52.9722C51.6232 108.799 50.8805 107.233 51.7338 106.188L112.32 32H120.719L105.764 71.4325Z" fill="white"/>
+</g>
+<defs>
+<clipPath id="clip0_354_3823">
+<rect width="192" height="192" fill="white" transform="translate(32 32)"/>
+</clipPath>
+</defs>
+</svg>

package/assets/logos/mcp.svg

@@ -0,0 +1,11 @@
+<svg width="180" height="180" viewBox="0 0 180 180" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect width="180" height="180" rx="24" fill="black"/>
+<mask id="mask0_246_1229" style="mask-type:luminance" maskUnits="userSpaceOnUse" x="7" y="7" width="166" height="166">
+<path d="M173 7H7V173H173V7Z" fill="white"/>
+</mask>
+<g mask="url(#mask0_246_1229)">
+<path d="M23.5996 85.2532L86.2021 22.6507C94.8457 14.0071 108.86 14.0071 117.503 22.6507C126.147 31.2942 126.147 45.3083 117.503 53.9519L70.2254 101.23" stroke="white" stroke-width="11.0667" stroke-linecap="round"/>
+<path d="M70.8789 100.578L117.504 53.952C126.148 45.3083 140.163 45.3083 148.806 53.952L149.132 54.278C157.776 62.9216 157.776 76.9357 149.132 85.5792L92.5139 142.198C89.6327 145.079 89.6327 149.75 92.5139 152.631L104.14 164.257" stroke="white" stroke-width="11.0667" stroke-linecap="round"/>
+<path d="M101.853 38.3013L55.553 84.6011C46.9094 93.2447 46.9094 107.258 55.553 115.902C64.1966 124.546 78.2106 124.546 86.8543 115.902L133.154 69.6025" stroke="white" stroke-width="11.0667" stroke-linecap="round"/>
+</g>
+</svg>