@oobe-protocol-labs/sap-mcp-server 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -2,8 +2,39 @@
 
 All notable changes to this project are documented in this file.
 
+## 0.2.0 - 2026-07-02
+
+### Security
+
+- Removed all known npm audit findings in the pnpm dependency graph; `pnpm audit --audit-level moderate` now exits cleanly.
+- Upgraded the test/runtime toolchain to patched `vitest@4.1.9`, `vite@8.1.3`, and `esbuild@0.28.1`.
+- Forced transitive `ws` resolution to `8.21.0` to avoid the memory-exhaustion DoS advisory.
+- Vendored a pure JavaScript `bigint-buffer@1.1.6` compatibility package because the public package has a native binding advisory and no patched `1.1.6` release is published on npm.
+- Raised the supported runtime to Node.js `>=22.12.0` and pnpm `11.7.0`, matching the Ink-based wizard and release lockfile behavior.
+
+### Changed
+
+- Bumped package and server metadata to `0.2.0`.
+- Added explicit pnpm workspace security policy for dependency overrides and approved native build scripts.
+
+### Verification
+
+- `pnpm audit --audit-level moderate`
+- `pnpm run typecheck`
+- `pnpm run lint`
+- `pnpm test -- --run`
+- `pnpm run build`
+- `pnpm run verify:release`
+
 ## 0.1.1 - 2026-06-29
 
+### Added
+
+- Added SAP session-ledger chat tools for deterministic public rooms, signed thematic group chats, chunked message writes, latest/all history reads, room status, and ledger sealing.
+- Added `sap_chat_publish_manifest` so agents can publish signed room/group manifests for discovery indexers and policy-aware clients.
+- Added on-chain agent chat documentation covering signed write proofs, room manifests, message envelopes, history fetching, IPFS/link sharing, privacy boundaries, and SDK-native `ChatManager` roadmap.
+- Added a bundled `sap-agent-chat` skill so MCP clients can load correct group-room, manifest discovery, link sharing, history, and privacy instructions.
+
 ### Fixed
 
 - Fixed `npx`/`npm exec` startup for the default `sap-mcp-server` and `sap-mcp-remote` binaries by adding resolver-safe bootstrap entrypoints.
@@ -36,7 +67,7 @@ All notable changes to this project are documented in this file.
 - Hosted MCP onboarding now states that users connect to the hosted URL while x402/pay.sh payments and value-moving tool transactions still require a wizard-created user SAP profile and user-controlled signer.
 - Remote hosted deployments now publish `/.well-known/sap-mcp-wizard.json` and `/wizard/install.sh` so agents can direct users to the wizard when local SAP MCP config is missing or inaccessible.
 - Agent context prompts now instruct agents to preserve the user's request language and avoid exposing keypair material.
-- Tool documentation now reflects the current runtime registry: 232 tools.
+- Tool documentation now reflects the current runtime registry and requires verification through `tools/list` because upstream SDK tool counts evolve.
 - Remote HTTP transports can now gate paid tool calls before execution and settle x402 payments after successful MCP responses.
 - Monetization now requires an explicit facilitator URL and documents OOBE hosted/self-hosted facilitator deployment.
 - Hybrid policy logging now uses the structured runtime logger instead of direct console output.

package/README.md

@@ -9,11 +9,13 @@ SAP MCP exposes the same typed tool registry through two supported MCP launch mo
 
 It also includes a professional setup wizard, profile-managed config under `~/.config/mcp-sap`, optional Bento policy integration, local and external signing modes, x402 monetization, a self-hosted OOBE facilitator, pay.sh provider YAML generation, and an A2A-compatible discovery card.
 
+User-facing setup docs live in [`USER_DOCS/`](USER_DOCS/00_START_HERE.md). Operator and engineering docs live in [`docs/`](docs/00_README.md).
+
 ## 1. Status
 
 | Area | Current behavior |
 | --- | --- |
-| Package version | `0.1.1` |
+| Package version | `0.2.0` |
 | MCP transport | stdio locally, Streamable HTTP remotely |
 | Remote access | Bearerless public mode for hosted agents; API key or JWT for private modes |
 | Config directory | `~/.config/mcp-sap` only |
@@ -26,6 +28,15 @@ It also includes a professional setup wizard, profile-managed config under `~/.c
 
 ## 2. Install
 
+Prerequisites:
+
+```bash
+node --version   # >= 22.12.0
+corepack enable
+corepack prepare pnpm@11.7.0 --activate
+pnpm --version   # 11.7.0
+```
+
 From source:
 
 ```bash
@@ -33,6 +44,8 @@ pnpm install
 pnpm run build
 ```
 
+Do not use `npm install` for source deployments. This repository is locked and verified with pnpm.
+
 From the published package:
 
 ```bash
@@ -102,6 +115,9 @@ Production environment values should come from a private secret store or private
 Remote endpoints:
 
 ```text
+GET     /
+GET     /server.json
+GET     /favicon.png
 GET     /health
 GET     /.well-known/agent-card.json
 GET     /.well-known/sap-mcp-wizard.json
@@ -111,6 +127,8 @@ GET     /mcp
 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.
+
 See [05. Remote VPS Deployment](docs/05_REMOTE_VPS_DEPLOYMENT.md) and [07. Endpoints And Clients](docs/07_ENDPOINTS_AND_CLIENTS.md).
 
 ## 6. Monetization
@@ -193,6 +211,7 @@ Start with [00. Documentation Index](docs/00_README.md).
 | [09. Tools, Skills, And Agent Guide](docs/09_TOOLS_SKILLS_AND_AGENT_GUIDE.md) | Tool families, SDK doc pointers, skills, and agent behavior. |
 | [10. Operations, Release, And PM2](docs/10_OPERATIONS_RELEASE_AND_PM2.md) | Quality gates, PM2, secrets, release packaging, and changelog discipline. |
 | [11. Code Quality Audit](docs/11_CODE_QUALITY_AUDIT.md) | Current engineering scorecard, release gates, quality rules, and residual risks. |
+| [12. On-Chain Agent Chat](docs/12_ONCHAIN_AGENT_CHAT.md) | Signed thematic group chat, room manifests, retrieval, link sharing, privacy boundaries, and SDK roadmap. |
 
 ## 9. Repository Layout
 
@@ -208,7 +227,7 @@ src/
   security/      Private-key, unsafe-action, and permission guards
   server/        MCP server factory and capability registration
   signer/        Local, delegated, and external signer adapters
-  tools/         SAP, Solana, AgentKit, SNS, profile, skill, and payment tools
+  tools/         SAP, Solana, AgentKit, SNS, profile, skill, chat, and payment tools
   transports/    stdio and local HTTP transport helpers
 ```
 

package/USER_DOCS/00_START_HERE.md

@@ -0,0 +1,130 @@
+# SAP MCP User Docs
+
+## 1. What SAP MCP Provides
+
+SAP MCP is the hosted and local Model Context Protocol gateway for OOBE Protocol's Synapse Agent Protocol stack. It gives MCP-compatible agents access to SAP identity, discovery, reputation, memory, SNS, x402 payment flows, Solana protocol tools, and bundled SAP skills.
+
+Use one of two deployment modes:
+
+| Mode | Endpoint | Best For |
+| --- | --- | --- |
+| Hosted remote MCP | `https://mcp.sap.oobeprotocol.ai/mcp` | Users and agents that want OOBE-hosted tools over Streamable HTTP |
+| Local stdio MCP | `node dist/cli.js` or `npx sap-mcp-server` | Local development, dedicated wallet profiles, local signing |
+
+## 2. Hosted Remote MCP Quick Start
+
+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:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+```
+
+Show the active profile:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config show
+```
+
+Hosted MCP URL:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/mcp
+```
+
+Wizard descriptor:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/.well-known/sap-mcp-wizard.json
+```
+
+## 3. What The Wizard Creates
+
+The wizard creates an isolated profile under:
+
+```txt
+~/.config/mcp-sap/
+```
+
+Typical layout:
+
+```txt
+~/.config/mcp-sap/
+  config.json
+  config-<profile>.json
+  keypairs/
+    <profile>-keypair.json
+```
+
+The wizard does not modify the Solana CLI keypair unless the user explicitly points a profile at it. The recommended path is a dedicated SAP MCP keypair per agent profile.
+
+## 4. MCP Client Setup
+
+Use hosted remote MCP in MCP-compatible clients by pointing the client at:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/mcp
+```
+
+The wizard can inject client config automatically for Claude, Hermes, OpenClaw, and Codex, or print manual snippets.
+
+Minimal hosted MCP client concept:
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "url": "https://mcp.sap.oobeprotocol.ai/mcp",
+      "transport": "streamable-http"
+    }
+  }
+}
+```
+
+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.
+
+## 5. Safety Rules For Agents
+
+Agents should follow these rules:
+
+1. Never read keypair bytes.
+2. Never print wallet secret material.
+3. Use `sap_profile_current` before operational work.
+4. Use preview/sign/submit flows for transactions.
+5. Ask for user approval when policy requires it.
+6. Treat hosted paid tools as x402/pay.sh-gated resources.
+7. Load SAP MCP skills before using advanced tools.
+
+## 6. Core User Commands
+
+```bash
+# Start the guided wizard
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+
+# Show active config
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config show
+
+# Show active profile metadata
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config profile-info
+
+# List pending secure config changes
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config pending
+
+# Approve or deny a protected config change
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config approve <id>
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config deny <id>
+
+# Show audit log
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config audit
+```
+
+## 7. Docs Map
+
+| File | Purpose |
+| --- | --- |
+| `01_HOSTED_REMOTE_MCP.md` | Hosted setup for users and agents |
+| `02_LOCAL_STDIO_MCP.md` | Local stdio setup and wallet profile flow |
+| `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 |

package/USER_DOCS/01_HOSTED_REMOTE_MCP.md

@@ -0,0 +1,106 @@
+# Hosted Remote MCP
+
+## 1. Endpoint
+
+Use the OOBE-hosted SAP MCP endpoint:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/mcp
+```
+
+Discovery endpoints:
+
+```txt
+https://mcp.sap.oobeprotocol.ai/
+https://mcp.sap.oobeprotocol.ai/server.json
+https://mcp.sap.oobeprotocol.ai/health
+https://mcp.sap.oobeprotocol.ai/.well-known/agent-card.json
+https://mcp.sap.oobeprotocol.ai/.well-known/sap-mcp-wizard.json
+https://mcp.sap.oobeprotocol.ai/wizard/install.sh
+https://mcp.sap.oobeprotocol.ai/favicon.png
+```
+
+The root page is safe to share publicly. It exposes professional metadata, favicon/social preview tags, and public endpoint information only. It must never expose RPC API keys, keypair paths, private VPS paths, or signer material.
+
+## 2. Why Hosted Users Still Need The Wizard
+
+Hosted MCP executes tools remotely, but the user's wallet and signer should remain local or externally controlled. The wizard creates:
+
+- an isolated SAP MCP profile;
+- a dedicated wallet path or external signer reference;
+- policy limits;
+- optional MCP client config injection;
+- local context for agents that need to sign x402/pay.sh payloads or Solana transactions.
+
+The hosted server does not expose or store keypair bytes.
+
+Read-only discovery can connect directly to the hosted MCP URL. Any agent that needs to sign x402/pay.sh payloads, SAP transactions, Solana transactions, SNS operations, or settlement actions should run the wizard first so the signer remains user-controlled.
+
+## 3. Install And Configure
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+```
+
+Select hosted remote MCP when asked how the client should connect.
+
+Then verify:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config show
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config profile-info
+```
+
+## 4. Test Hosted MCP Manually
+
+Initialize:
+
+```bash
+curl -iN https://mcp.sap.oobeprotocol.ai/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl-smoke","version":"0.1.0"}}}'
+```
+
+Copy the returned `mcp-session-id`, then list tools:
+
+```bash
+curl -iN https://mcp.sap.oobeprotocol.ai/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'mcp-session-id: <SESSION_ID>' \
+  -H 'mcp-protocol-version: 2025-06-18' \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
+```
+
+## 5. Free Tool Smoke Test
+
+```bash
+curl -iN https://mcp.sap.oobeprotocol.ai/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'mcp-session-id: <SESSION_ID>' \
+  -H 'mcp-protocol-version: 2025-06-18' \
+  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"sap_profile_current","arguments":{}}}'
+```
+
+The RPC URL in returned metadata must be redacted if it contains query secrets.
+
+## 6. Paid Tool Smoke Test
+
+```bash
+curl -iN https://mcp.sap.oobeprotocol.ai/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'mcp-session-id: <SESSION_ID>' \
+  -H 'mcp-protocol-version: 2025-06-18' \
+  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"sap_list_all_agents","arguments":{"limit":5}}}'
+```
+
+Expected result without payment proof:
+
+```txt
+HTTP/1.1 402 Payment Required
+```
+
+The response includes x402 payment instructions. Agents that support x402 can sign the payment payload and replay the exact request with the payment header.

package/USER_DOCS/02_LOCAL_STDIO_MCP.md

@@ -0,0 +1,91 @@
+# Local Stdio MCP
+
+## 1. When To Use Local Mode
+
+Use local stdio mode when:
+
+- the MCP client does not support remote Streamable HTTP;
+- the user wants the entire MCP server running locally;
+- transaction signing must happen on the user's machine;
+- development or integration testing needs local logs.
+
+## 2. Create A Profile
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
+```
+
+Recommended mode for local non-transactional inspection:
+
+```txt
+readonly
+```
+
+Recommended mode for local signing with a dedicated SAP wallet:
+
+```txt
+local-dev-keypair
+```
+
+Recommended mode for hardware/KMS/managed signers:
+
+```txt
+external-signer
+```
+
+## 3. Start Local MCP
+
+Installed package:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-server
+```
+
+From a cloned repo:
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+node dist/bin/sap-mcp-server.js
+```
+
+## 4. Config Directory
+
+SAP MCP uses:
+
+```txt
+~/.config/mcp-sap
+```
+
+Do not use the legacy path:
+
+```txt
+~/.config/sap-mcp
+```
+
+Do not store SAP MCP keypairs in:
+
+```txt
+~/.config/solana/id.json
+```
+
+unless the user intentionally chooses to reuse the Solana CLI identity.
+
+## 5. Local Client Config Concept
+
+```json
+{
+  "mcpServers": {
+    "sap": {
+      "command": "node",
+      "args": ["/absolute/path/to/sap-mcp-server/dist/bin/sap-mcp-server.js"],
+      "cwd": "/absolute/path/to/sap-mcp-server",
+      "env": {
+        "SAP_MCP_PROFILE": "default"
+      }
+    }
+  }
+}
+```
+
+The wizard can generate or inject the correct client config.

package/USER_DOCS/03_PAYMENTS_X402_PAYSH.md

@@ -0,0 +1,212 @@
+# Payments: x402, pay.sh Pay-Per-Use, And pay.sh Subscriptions
+
+## 1. Payment Layers
+
+SAP MCP supports two complementary payment layers:
+
+| Layer | Purpose |
+| --- | --- |
+| Native x402 gate | Per-tool pricing inside hosted SAP MCP. Free tools remain free; premium tool calls return `402 Payment Required`. |
+| pay.sh gateway | Optional outer HTTP gateway for metered pay-per-use endpoints or subscription-gated endpoints. |
+
+Native SAP MCP x402 is authoritative per tool call. pay.sh is useful when exposing SAP MCP or adjacent HTTP APIs through a cataloged pay gateway.
+
+Recommended split:
+
+- use native SAP MCP x402 when the price depends on the MCP tool being called;
+- use pay.sh pay-per-use when a normal HTTP route should charge per request or per measured unit;
+- use pay.sh subscriptions when a route should be flat-fee access for a fixed period.
+
+Do not put `metering:` and `subscription:` on the same pay.sh endpoint. Use separate endpoints or separate provider specs.
+
+## 2. Native x402 Tool Pricing
+
+Free:
+
+- `tools/list`
+- `prompts/list`
+- `resources/list`
+- `sap_profile_current`
+- basic overview/profile tools
+
+Paid examples:
+
+- premium reads such as `sap_list_all_agents`;
+- enriched discovery and network analytics;
+- SNS batch checks and builder tools;
+- value-changing payment/settlement flows.
+
+Without payment, a paid tool returns:
+
+```txt
+HTTP/1.1 402 Payment Required
+```
+
+The response contains payment instructions and the caller replays the same request with the payment header.
+
+Hosted SAP MCP accepts payment proof headers used by the x402/payment flow and exposes settlement headers back to the caller:
+
+| Direction | Header |
+| --- | --- |
+| Client payment proof | `PAYMENT-SIGNATURE` or `X-PAYMENT` |
+| 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.
+
+## 3. 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.
+
+References:
+
+- https://pay.sh/docs/building-with-pay/getting-started
+- https://pay.sh/docs/building-with-pay/pricing
+- https://pay.sh/docs/building-with-pay/yaml-specification
+
+Generate a SAP MCP pay.sh spec:
+
+```bash
+npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-pay-sh-spec \
+  --out sap-mcp-pay-sh.yml \
+  --upstream-url https://mcp.sap.oobeprotocol.ai \
+  --network mainnet \
+  --recipient <OOBE_REVENUE_WALLET>
+```
+
+Example metered block:
+
+```yaml
+endpoints:
+  - method: POST
+    path: 'mcp'
+    description: 'SAP MCP JSON-RPC endpoint.'
+    metering:
+      dimensions:
+        - direction: usage
+          unit: requests
+          scale: 1
+          tiers:
+            - price_usd: 0.008
+```
+
+pay.sh metered rules to keep:
+
+1. Free endpoints omit both `metering:` and `subscription:`.
+2. Simple per-call endpoints use `unit: requests` and `scale: 1`.
+3. Token, character, page, byte, or variant pricing should only be used when that unit is the real cost driver.
+4. Prices must remain representable in 6-decimal stablecoins.
+5. With `routing.type: proxy`, the gateway forwards only verified paid requests to the upstream.
+6. The gateway endpoint allowlist is explicit; routes not listed in `endpoints[]` are not exposed by pay.sh.
+
+For SAP MCP, keep pay.sh upstream credentials in environment variables, not in the public YAML:
+
+```yaml
+routing:
+  type: proxy
+  url: https://mcp.sap.oobeprotocol.ai/
+operator:
+  currencies:
+    usd: ['USDC']
+  network: mainnet
+  recipient: '<OOBE_REVENUE_WALLET>'
+```
+
+## 4. 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.
+
+References:
+
+- https://pay.sh/docs/building-with-pay/subscriptions/concept
+- https://pay.sh/docs/building-with-pay/subscriptions/yaml-specification
+- https://pay.sh/docs/building-with-pay/subscriptions/examples
+
+Example subscription endpoint:
+
+```yaml
+endpoints:
+  - method: POST
+    path: 'mcp/subscription'
+    description: 'SAP MCP subscription access. Proxy/rewrite this endpoint to the MCP upstream when enabled.'
+    subscription:
+      period: '30d'
+      price_usd: 49.00
+      currency: USDC
+```
+
+Operational notes:
+
+1. `period` accepts fixed days or weeks such as `30d`, `1w`, or `52w`.
+2. Month units are not valid because pay.sh periods are fixed elapsed time.
+3. The first launch publishes an on-chain Plan PDA when no `plan_id` exists.
+4. The generated `plan_id`, numeric plan metadata, and created-at metadata may be written back into the YAML by pay.sh.
+5. Use separate endpoints for pay-per-use and subscription access.
+6. A subscription endpoint is one price, one period, one endpoint. Build tier upgrades or prorations in your own product layer if needed.
+7. Subscription tiers are separate endpoints, each with its own `Plan` PDA.
+8. The subscriber activates once; repeated calls during the active period should not prompt for another payment.
+
+Example product split for SAP MCP remote access:
+
+```yaml
+endpoints:
+  - method: POST
+    path: 'mcp'
+    description: 'SAP MCP metered tool access.'
+    metering:
+      dimensions:
+        - direction: usage
+          unit: requests
+          scale: 1
+          tiers:
+            - price_usd: 0.008
+
+  - method: POST
+    path: 'mcp/pro'
+    description: 'SAP MCP pro subscription access, 30-day billing period.'
+    subscription:
+      period: '30d'
+      price_usd: 49.00
+      currency: USDC
+```
+
+When using a subscription route in front of MCP, route or rewrite it to the upstream MCP server after pay.sh verifies the subscription. The MCP protocol endpoint itself remains `/mcp` on the upstream server.
+
+Subscriber commands:
+
+```bash
+# First call activates the subscription.
+pay curl https://<pay-sh-provider-host>/mcp/pro
+
+# Inspect active subscriptions.
+pay subscriptions list
+pay subscriptions list --network mainnet
+pay subscriptions list --json
+```
+
+## 5. Recommended OOBE Product Split
+
+| Product | Payment Model |
+| --- | --- |
+| Basic hosted discovery | Free |
+| Premium reads | Native x402 per tool |
+| Heavy analytics/builders | Native x402 per tool or pay.sh metered endpoint |
+| Pro remote access | pay.sh subscription endpoint |
+| Enterprise/custom routing | Dedicated subscription endpoint or private contract |
+
+## 6. 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
+- Provider YAML specification: https://pay.sh/docs/building-with-pay/yaml-specification
+- Subscriptions concept: https://pay.sh/docs/building-with-pay/subscriptions/concept
+- 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
+
+- Never put RPC API keys in public YAML.
+- Never put private keypair paths in public docs.
+- Use environment variables for upstream credentials.
+- Keep facilitator and pay.sh operator keypairs separate from SAP agent wallets.
+- Rotate any API key that appeared in logs before redaction was enabled.