# 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 MCP Local Bridge 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.

Choose one setup path:

| 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.

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_WIZARD_INSTALL_RUNBOOK
```

### CLI Wizard

Run the wizard for a full hosted setup:

```bash
npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard
```

At the first menu, choose **Full hosted SAP MCP setup** for new profiles or
**Repair hosted runtime + sap_payments bridge only** when the profile already
exists and only paid/write hosted calls are failing.

Repair without walking through the full wizard:

```bash
npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config repair
```

1. Full setup creates or imports the dedicated local SAP MCP wallet profile.
2. Repair keeps the active profile and only fixes OOBE `sap`/`sap_payments` runtime entries.
3. Let the wizard configure hosted `sap` plus local `sap_payments` for supported runtimes.
4. Use `sap_payments_call_paid_tool` when a hosted SAP MCP tool requires x402 payment.
5. Use `sap_payments_call_external_x402` when an external HTTP x402 agent endpoint is discovered through SAP registry metadata.
6. Use `sap_protocol_invariants` before registry writes when treasury, fee, or hosted/local routing is unclear.
7. Use `sap_payments_register_agent` when hosted `sap_register_agent` returns `hosted_local_signer_required`.
8. Use `sap_payments_update_agent` when hosted `sap_update_agent` returns `hosted_local_signer_required`; this is the preferred path for public agent image/profile metadata updates.
9. For registrations, check `success`, `agentRegistered`, `agentPda`, `protocolFee`, and `protocolComplete`. Local registration does not pay a hosted x402 fee. `success: true` means the agent account exists and the source-level protocol fee invariant was verified. If `success: false` with `agentRegistered: true`, the account may exist but SAP registration is not protocol-complete.
10. Use `sap_payments_finalize_transaction` when a paid hosted builder returns an unsigned transaction to preview, sign locally, and optionally submit already-signed bytes through the hosted OOBE relay.
11. Use `sap_agent_runtime_status` when asking an agent whether SAP MCP is connected or ready for paid/write work. It returns the hosted/local bridge routing truth without reading local files.
12. Use `sap_prepare_action` before swaps, registry writes, identity updates, Escrow V2, external x402 calls, premium streams, or transaction finalization. It returns fresh-data requirements, the correct hosted/local route, confirmation policy, retry rules, and proof-tape fields without charging x402.
13. Use `sap_agent_standard_context` when an agent needs to understand SAP MCP's MCP/x402/pay.sh, A2A-style agent-card, OASF-style export, AP2-style mandate, local signing, and hosted-builder boundaries before making public claims or composing cross-agent workflows.
14. Use `sap_prepare_mandate` before bounded agent-commerce work. It returns an unsigned planning artifact with spend caps, allowed tools/protocols, confirmation thresholds, expiry, and proof-tape fields. It is not a wallet signature and does not authorize payment by itself.
15. Use `sap_export_agent_oasf` when a known owner wallet needs a machine-readable OASF-style profile export for directories or agent networks.
16. Use `sap_pricing_catalog` or `https://mcp.sap.oobeprotocol.ai/pricing.json` to inspect generated hosted pricing tiers. The x402 challenge returned by a paid tool remains the final payment source of truth.

Session memory is for operational context and audit: active profile name after
readiness, public wallet keys, runtime namespace availability, x402 receipts,
submitted signatures, final statuses, and error classifications. Do not use
memory as cached truth for balances, token prices, Jupiter quotes/orders,
blockhashes, simulations, liquidity/routes, SNS ownership, or SAP account state.

Agent identity, profile images, Metaplex bridging, SNS linking, capabilities,
pricing, and update fields are documented in:

```txt
https://mcp.sap.oobeprotocol.ai/docs/#/16_AGENT_IDENTITY_REGISTRY_PIPELINE
```

Agents can discover the same recovery path without guessing. The hosted SAP MCP
server exposes these free maintenance tools:

| Tool | Purpose |
| --- | --- |
| `sap_agent_start` | Load the canonical startup playbook. |
| `sap_agent_runtime_status` | Free runtime truth table for hosted connection, local `sap_payments` readiness expectations, write routing, forbidden actions, and next tool calls. |
| `sap_prepare_action` | Free intent-level planner for paid calls, writes, swaps, escrow, external x402, premium streams, confirmation policy, retry rules, and proof-tape shape. |
| `sap_agent_standard_context` | Free standards-aware routing map for MCP, x402/pay.sh, A2A-style metadata, OASF-style exports, AP2-style mandates, and public claim boundaries. |
| `sap_prepare_mandate` | Free unsigned agent-commerce mandate draft with spend limits, allow-lists, expiry, confirmation policy, and proof-tape template. |
| `sap_export_agent_oasf` | Free exact owner-wallet export of SAP agent identity, capabilities, protocols, pricing, x402 endpoint, and trust facts in an OASF-style shape. |
| `sap_pricing_catalog` | Free machine-readable pricing catalog generated from the hosted pricing registry. Also available at `/pricing.json`. |
| `sap_protocol_invariants` | Return the canonical SAP program id, protocol treasury, registration fee, hosted/local routing rules, and forbidden actions. |
| `sap_agent_identity_plan` | Free planner for SAP registration, image/profile updates, Metaplex identity, SNS linking, and verification. |
| `sap_skills_upgrade_plan` | Return latest-release skill upgrade commands and target directories. |
| `sap_runtime_repair_plan` | Return the pinned repair command and expected `sap_payments` bridge tools after restart. |

If an agent says the local `sap_payments` bridge is missing, ask it to call
`sap_runtime_repair_plan` before asking you to edit JSON, TOML, or YAML by hand.

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
```

Hosted documentation:

```txt
https://mcp.sap.oobeprotocol.ai/docs
```

Hosted pricing catalog:

```txt
https://mcp.sap.oobeprotocol.ai/pricing.json
```

Client config docs:

```txt
https://mcp.sap.oobeprotocol.ai/docs/#/user/04_MCP_CLIENT_CONFIGURATION_MATRIX
```

Payment docs:

```txt
https://mcp.sap.oobeprotocol.ai/docs/#/user/03_X402_PAYSH_PAID_TOOL_RUNBOOK
```

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"
    }
  }
}
```

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

Agents should follow these rules:

1. Never read keypair bytes.
2. Never print wallet secret material.
3. Use `sap_payments_wallet_guard`, `sap_payments_profile_current`, and `sap_payments_readiness` before paid/write hosted work.
4. Use `sap_profile_current` only for hosted server state; do not infer the local user wallet from it.
5. Use `sap_payments_process_status` before retrying stuck paid calls or bridge errors.
6. Use preview/sign/submit flows for transactions.
7. Ask for user approval when policy requires it.
8. Treat hosted paid tools as x402/pay.sh-gated resources.
9. 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

# Check local runtime readiness
npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config doctor

# 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_MCP_LOCAL_BRIDGE_SETUP.md` | Hosted setup for users and agents |
| `02_LOCAL_STDIO_PROFILE_SIGNER_SETUP.md` | Local stdio setup and wallet profile flow |
| `03_X402_PAYSH_PAID_TOOL_RUNBOOK.md` | x402, pay.sh pay-per-use, and pay.sh subscriptions |
| `04_MCP_CLIENT_CONFIGURATION_MATRIX.md` | Claude, Hermes, Codex, OpenClaw config examples |
| `05_AGENT_SKILLS_TOOL_ROUTING.md` | Skills, tool selection, and security behavior |
| `06_DESKTOP_WIZARD_INSTALL_RUNBOOK.md` | Desktop GUI wizard install, hosted setup, local payment bridge, and runtime behavior |
| `07_SMITHERY_MARKETPLACE_INTEGRATION.md` | Smithery setup schema, marketplace usage, native x402 clients, and local bridge guidance |