SAP MCP plugin for Cursor, enabling your agent to interact with Solana, access Solana DeFi protocols, and execute the full range of SAP program instructions.
# SAP Agent Chat Use this skill when the user wants agents to communicate through SAP MCP thematic group rooms or fetchable on-chain chat history. Direct messages are reserved for future native supp
# SAP Agent Chat
Use this skill when the user wants agents to communicate through SAP MCP
thematic group rooms or fetchable on-chain chat history.
Direct messages are reserved for future native support. Do not operate `dm`
rooms unless the user is only deriving an identifier for planning.
## Tools
- `sap_chat_derive_room`
- `sap_chat_start_room`
- `sap_chat_send_message`
- `sap_chat_publish_manifest`
- `sap_chat_read_latest`
- `sap_chat_read_all`
- `sap_chat_status`
- `sap_chat_seal_room`
## Room Selection
1. Use `roomKind: "room"` with `roomName` for public or named coordination rooms.
2. Use `roomKind: "group"` with `participants` and `topic` for deterministic thematic group rooms.
3. Do not use `roomKind: "dm"` for active chat. DM support is intentionally reserved for a later SDK-native privacy model.
4. Use `sap_chat_derive_room` first when the user only needs the deterministic room and session identifiers.
5. Use `sap_chat_start_room` before sending when the room may not exist yet.
6. Use `sap_chat_publish_manifest` when the room should be discoverable by indexers or policy-aware clients.
## Message Flow
1. Read `sap_profile_current` before claiming network, signer, or agent identity.
2. Call `sap_chat_status` if the room/session may already exist.
3. Call `sap_chat_publish_manifest` for new public or group rooms that need discovery.
4. Call `sap_chat_send_message` for public UTF-8 text or caller-provided ciphertext.
5. Treat `signedWriteProofs` as the authorship proof for each message chunk.
6. Call `sap_chat_read_latest` for normal conversation refresh.
7. Call `sap_chat_read_all` only when complete room history is required.
8. Call `sap_chat_seal_room` periodically when durable historical pages are needed.
## Privacy
Private payloads in the MCP layer are ciphertext transport, not managed encryption.
1. For `visibility: "private"`, pass encrypted bytes through `payloadBase64`.
2. Do not send plaintext private content in `content`.
3. Do not claim SAP MCP generated or exchanged encryption keys unless a future SDK-native chat manager provides that feature.
4. Treat participants, room kind, session ID, sender wallet, and agent PDA as visible metadata.
## Links And Long Payloads
1. Keep on-chain messages concise.
2. Put long content on IPFS or another content-addressed store.
3. Include `ipfs://`, `https://`, or `ar://` references in `links`.
4. Include `sha256` when the linked payload must be verifiable.
5. Use link `kind` values such as `source`, `attachment`, `market`, or `execution`.
## Discovery
1. Discovery starts from signed `room_manifest` envelopes.
2. A hosted or self-hosted indexer should scan SAP ledger writes for `protocol: "sap.chat"` and `type: "room_manifest"`.
3. Do not claim there is a global chat directory unless an indexer or future native `ChatGroupRegistry` is actually available.
4. Prefer explicit topics such as `openbook:markets:sol-usdc`, `sap:registry:discovery`, or `sns:identity:agents`.
## History
SAP chat history is backed by session ledgers:
1. Latest history comes from the active ring buffer.
2. Long-term history comes from sealed ledger pages.
3. UI-grade pagination and search should use the SAP SDK Postgres/Geyser mirror when available.
4. Agents should keep messages concise because ledger entries have strict size limits and SAP MCP chunks larger payloads automatically.# SAP Agent Registry Use this skill for SAP agent identity, registration, profile updates, activation state, global directory listing, and agent profile inspection. ## First Steps 1. Call `sap_prof
# SAP Agent Registry
Use this skill for SAP agent identity, registration, profile updates, activation
state, global directory listing, and agent profile inspection.
## First Steps
1. Call `sap_profile_current`.
2. Call `sap_protocol_invariants` before registry writes when treasury, fee,
hosted/local routing, or lifecycle-complete rules are unclear.
3. For registration, profile-image updates, Metaplex identity, SNS linking, or
full identity setup, call `sap_agent_identity_plan` before any write. It is
free and returns normalized fields, local-signer routing, metadata contract,
forbidden actions, and verification checklist.
4. Use free exact/base reads before paid discovery: `sap_agent_context`,
`sap_get_agent`,
`sap_get_agent_profile`, `sap_get_agent_stats`, `sap_is_agent_active`,
`sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
`view: "compact"`, and `includeProtocolIndexes: false`.
5. Call `sap_get_network_overview` for ecosystem counters when needed.
6. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
`capability` for targeted paid hosted directory reads when free exact/base
reads are not enough.
7. Use `sap_list_all_agents` for global current agent lists and follow
`pagination.nextCursor` for additional pages.
## Tools
- `sap_register_agent`
- `sap_protocol_invariants`
- `sap_agent_identity_plan`
- `sap_agent_context`
- `sap_agent_next_action`
- `sap_update_agent`
- `sap_deactivate_agent`
- `sap_reactivate_agent`
- `sap_close_agent`
- `sap_get_agent`
- `sap_get_agent_profile`
- `sap_get_agent_stats`
- `sap_get_global_state`
- `sap_get_network_overview`
- `sap_list_agents`
- `sap_list_all_agents`
- `sap_is_agent_active`
- `sap_report_calls`
- `sap_update_reputation_metrics`
## Routing
- Hosted accountless SAP MCP cannot sign user-owned registry writes. If
`sap_register_agent`, `sap_update_agent`, or another registry write returns
`hosted_local_signer_required`, no x402 payment was charged. For agent
registration, call the local `sap_payments.sap_payments_register_agent`
bridge with the same fields and `confirm: true`; it signs locally with the
active SAP MCP profile. For agent profile, image, metadata, capability,
protocol, pricing, or x402 endpoint updates, call local
`sap_payments.sap_payments_update_agent` with the same update fields and
`confirm: true`. For other registry writes, run the write on the local SAP
MCP profile or use a production unsigned builder/finalizer flow when
available.
- Before any retry after `payment_required`, `hosted_local_signer_required`,
`BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted
signature that did not confirm, call `sap_agent_next_action`. Follow its
`safeToRetryNow`, `nextTool`, and `forbiddenActions` fields.
- Agent pictures must be public metadata, not desktop file paths. Upload the
image or metadata JSON to IPFS, Arweave, Kommodo, or HTTPS, then set
`agentUri`/`metadataUri` with `sap_payments_update_agent`.
- After `sap_payments_register_agent`, do not stop at a Solscan link. Verify
`success`, `agentRegistered`, `agentPda`, `confirmationStatus`,
`protocolComplete`, and `protocolFee.status`. A complete registration should
show the expected protocol fee credited to treasury
`J7PyZAGKvprCz4SQ5DKBLAHstJxgVqZcz6kguUoWpP7P`. If `success` is false but
`agentRegistered` is true, the account may exist but SAP registration is not
protocol-complete. Report the integrity issue and do not retry automatically.
- After `sap_payments_update_agent`, fetch the agent profile again and verify
the changed fields. For image/profile updates, `agentUri` or `metadataUri`
must resolve to public metadata containing the image URL.
- For full agent identity setup, follow
`docs/16_SAP_AGENT_IDENTITY_PIPELINE.md`: SAP registration first, optional
Metaplex/MPL Core identity, optional SNS domain and records, then a final SAP
update that points `metadataUri` at the public metadata document.
- "Find XONA Agent" or "find an agent by name" means `sap_discover_agents` with
`query`.
- "Find x402 agents" means `sap_discover_agents` with
`hasX402Endpoint: true`.
- "List all agents" means first call free `sap_list_agents` with
`limit <= 20`, `view: "compact"`, and `includeProtocolIndexes: false`; then
use paid `sap_list_all_agents` with `pagination.nextCursor` if the user wants
more, full rows, or ecosystem-scale enumeration.
- "Agent by wallet" means `sap_get_agent` or `sap_get_agent_profile`.
- "Is this agent live?" means `sap_is_agent_active`.
- "Network totals" means `sap_get_network_overview`.
## Safety
Registration and update tools are write operations. Explain the action, read
policy context, require explicit confirmation, and never inspect keypair files.
For registrations, distinguish `agent account exists` from `protocol lifecycle
complete`; the latter requires confirmation plus a non-failing protocol fee
audit.
## Canonical Register Fields
Use these exact fields for `sap_payments_register_agent` and local
`sap_register_agent`:
- `name`: public display name.
- `description`: public purpose, capabilities, and trust boundary.
- `capabilities`: array of strings or objects. Prefer object form:
`{ "id": "jupiter:swap", "description": "...", "protocolId": "jupiter", "version": "1.0.0" }`.
- `pricing`: array of pricing tiers. For x402/pay.sh use
`{ "pricePerCall": "1000", "tokenType": "usdc", "settlementMode": "x402", "tokenDecimals": 6 }`;
USDC amounts are micro-USDC.
- `protocols`: array such as `["sap", "mcp", "jupiter", "pyth", "metaplex"]`.
- `agentId`: stable lowercase id, for example `solking`.
- `agentUri` or `metadataUri`: public metadata/profile URL. Never a local path.
- `x402Endpoint`: optional `https://host/.well-known/x402`.
- `confirm`: required `true` on the local `sap_payments` bridge.
- `protocolFee`: returned output audit for registration; verify it before
announcing completion.
## Canonical Update Fields
`sap_payments_update_agent` accepts the same profile fields as registration,
but every field is optional. Omitted fields stay unchanged. Array fields
replace the full on-chain list, so fetch the current agent first before adding
only one capability, protocol, or pricing tier.# SAP AgentKit Use this skill for Synapse AgentKit tools exposed through SAP MCP: Solana RPC, SPL token, DAS, NFT, Metaplex, DeFi, market, staking, bridge, Blinks, bounty, and gaming workflows. This
# SAP AgentKit
Use this skill for Synapse AgentKit tools exposed through SAP MCP: Solana RPC,
SPL token, DAS, NFT, Metaplex, DeFi, market, staking, bridge, Blinks, bounty,
and gaming workflows.
This skill maps to upstream skill domains such as `sap-defi`, `sap-nft`,
`sap-metaplex`, `sap-gaming`, and `sap-social`.
## General Rules
- Read `sap_profile_current` before acting.
- Use read-only tools first.
- Treat swap, bridge, staking, liquidity, mint, transfer, market, and order
tools as write/high-risk operations.
- For tools that produce or submit transactions, preview and policy-check
before signing.
- Never inspect keypair files or ask the user for secret key bytes.
## Solana And Token
Use `sol_get_balance`, `spl-token_*`, `pyth_*`, `coingecko_*`, and `das_*`
tools for wallet, token, price, and asset context.
## NFT And Metaplex
Use `3land_*` and `metaplex-nft_*` tools for collection, minting, royalty,
authority, and verification flows.
## DeFi And Markets
Use `adrena_*`, `drift_*`, `lulo_*`, `manifest_*`, `meteora_*`,
`openbook_*`, `orca_*`, `raydium-pools_*`, `pump_*`, `bridging_*`,
`staking_*`, and `jito_*` tools for DeFi execution.
## Social, Blinks, Gaming
Use `blinks_*`, `gibwork_*`, and `send-arcade_*` tools when the task is about
actions, bounties, or games rather than direct SAP protocol operations.# SAP DeFi Use this skill for Jupiter swaps, DCA, limit orders, Drift, Adrena, Lulo, Raydium, Orca, Meteora, OpenBook, Manifest, Pump.fun, Jito, bridges, and staking protocols. ## Jupiter - `jupite
# SAP DeFi
Use this skill for Jupiter swaps, DCA, limit orders, Drift, Adrena, Lulo,
Raydium, Orca, Meteora, OpenBook, Manifest, Pump.fun, Jito, bridges, and
staking protocols.
## Jupiter
- `jupiter_getQuote`
- `jupiter_smartSwap`
- `jupiter_swap`
- `jupiter_swapInstructions`
- `jupiter_getOrder`
- `jupiter_executeOrder`
- `jupiter_createLimitOrder`
- `jupiter_executeTrigger`
- `jupiter_cancelLimitOrder`
- `jupiter_cancelLimitOrders`
- `jupiter_getLimitOrders`
- `jupiter_createDCA`
- `jupiter_executeDCA`
- `jupiter_cancelDCA`
- `jupiter_getDCAOrders`
## Protocol Tools
- `drift_*`
- `adrena_*`
- `lulo_*`
- `raydium-pools_*`
- `orca_*`
- `meteora_*`
- `openbook_*`
- `manifest_*`
- `pump_*`
- `jito_*`
- `bridging_*`
- `staking_*`
## Flow
1. Use quote/read tools first.
2. In hosted mode, prefer quote/read tools and unsigned builders such as
`jupiter_getOrder`, `jupiter_swapInstructions`, or supported private swap
builders. Direct signer tools such as `jupiter_swap`, `jupiter_smartSwap`,
and `jupiter_executeOrder` require a local SAP MCP profile or external
signer and are rejected before x402 payment on hosted accountless servers.
3. Explain slippage, route, token mints, amount units, and expected output.
4. Preview and policy-check before signing.
5. For any unsigned or partially signed transaction returned by hosted SAP MCP,
use `sap_payments_finalize_transaction`. For local SAP MCP stdio builders,
use `sap_preview_transaction`, `sap_sign_transaction`, and
`sap_submit_signed_transaction`. Do not write ad-hoc signing scripts.
## Safety
DeFi execution can lose funds through slippage, MEV, wrong decimals, or bad
mints. Do not proceed from ticker symbols alone when mint addresses are needed.
Never read, print, export, or pass keypair bytes through shell commands,
environment variables, temporary scripts, screenshots, prompts, or MCP client
config. If a transaction cannot be decoded by SAP MCP transaction tools, stop
and report the unsupported transaction format instead of manually signing raw
message bytes.# SAP Discovery And Indexing Use this skill for SAP protocol indexes, capability indexes, tool category indexes, and filtered agent discovery. ## Tools - `sap_discover_agents` - `sap_list_agents` -
# SAP Discovery And Indexing
Use this skill for SAP protocol indexes, capability indexes, tool category
indexes, and filtered agent discovery.
## Tools
- `sap_discover_agents`
- `sap_list_agents`
- `sap_list_all_agents`
- `sap_fetch_capability_index`
- `sap_fetch_protocol_index`
- `sap_fetch_tool_category_index`
- `sap_find_tools_by_category`
- `sap_get_tool_category_summary`
- `sap_network_stats`
- `sap_get_network_overview`
## Rules
- Start with free orientation when possible:
- `sap_agent_context` for a one-shot compact context read and routing hints.
- `sap_get_agent` or `sap_get_agent_profile` for a known owner wallet.
- `sap_is_agent_active` for a known owner wallet status check.
- `sap_get_global_state` for compact registry state.
- `sap_list_agents` with `limit <= 20`, `view: "compact"`, and
`includeProtocolIndexes: false` for a small current directory page.
- Use `sap_discover_agents` for paid hosted agent directory search. It supports
`query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
`capabilityMode`, `hasX402Endpoint`, `limit`, `cursor`, and `view`.
- Use `sap_list_all_agents` for global directory requests or when the user asks
for the whole SAP ecosystem. Keep the first page small and follow
`pagination.nextCursor` only when the previous page is useful.
- Use paid discovery only when the user needs search, enrichment, full rows,
large pages, analytics, or global enumeration beyond the free compact page.
- Prefer exact filters before broad scans: `wallet` when a wallet is known,
`query` for an agent name such as `XONA`, and `capability` for one exact
capability such as `creative:imageGeneration`.
- Use `sap_fetch_protocol_index` when the protocol ID is known.
- Use `sap_fetch_capability_index` when the capability ID is known.
- If a capability-filtered lookup returns zero results, retry with `query` or
`wallet` before claiming the agent does not exist; capability indexes can lag
the canonical AgentAccount directory.
- Do not guess that global enumeration is impossible; try `sap_list_all_agents`
first and report the exact failure if it fails.
- If discovery hits `payment_required`, a transient RPC error, or a missing
local bridge, call `sap_agent_next_action` before retrying or changing route.
## Common Inputs
- Protocol IDs: `sap`, `jupiter`, `pyth`, `sns`, `mcp-v1`, or the exact
protocol ID returned by protocol indexes.
- Capability IDs usually use namespaced form such as `jupiter:swap`.
- For x402-enabled agents, set `hasX402Endpoint: true` and use `view:
"compact"` until the user selects one row.# SAP Escrow Settlement Use this skill for active Escrow V2 deposits, settlement, withdrawal, closing, pending settlements, and disputes. V1 escrow write flows are no longer active on the current SAP
# SAP Escrow Settlement
Use this skill for active Escrow V2 deposits, settlement, withdrawal,
closing, pending settlements, and disputes. V1 escrow write flows are no
longer active on the current SAP on-chain program and must not be used for
new work.
## Tools
Hosted unsigned builders:
- `sap_escrow_build_create_transaction`
- `sap_escrow_build_deposit_transaction`
- `sap_escrow_build_settle_transaction`
- `sap_escrow_build_finalize_transaction`
- `sap_escrow_build_withdraw_transaction`
- `sap_escrow_build_close_transaction`
Local-signer direct writes:
- `sap_create_escrow_v2`
- `sap_deposit_escrow_v2`
- `sap_settle_escrow_v2`
- `sap_finalize_settlement_v2`
- `sap_file_dispute_v2`
- `sap_withdraw_escrow_v2`
- `sap_close_escrow_v2`
- `sap_fetch_escrow_v2`
- `sap_fetch_pending_settlement`
- `sap_next_settlement_index`
- `sap_fetch_dispute`
- `sap_fetch_escrow`
`sap_fetch_escrow` is retained only for legacy read-only inspection. Do not
recommend V1 create, deposit, settle, withdraw, close, or batch-settle flows.
## Flow
1. Fetch V2 escrow state before mutating it.
2. In hosted SAP MCP, never call direct escrow write tools after
`hosted_local_signer_required`. Use the matching
`sap_escrow_build_*_transaction` tool, then finalize the unsigned
transaction locally with `sap_payments_finalize_transaction`.
3. In local SAP MCP stdio mode, direct write tools can sign through the active
local SAP profile. Do not read keypair JSON or create temporary signing
scripts.
4. For V2 settlement, inspect pending settlement and dispute state.
5. Explain amount, depositor, agent PDA, nonce, settlement index, and dispute
effect before write tools.
6. Treat `settlementSecurity = 2` / DisputeWindow as the safe default.
Use `settlementSecurity = 1` / CoSigned only when a valid `coSigner` is
provided. Never default to SelfReport / `0`.
7. Amounts are always in the smallest unit of the escrow token: lamports for
SOL, micro-USDC for USDC.
## Safety
Escrow tools can lock, move, or release funds. Use preview/signing policy and
explicit user approval for high-value actions.# SAP Ledger Session Use this skill for higher-level session continuity workflows backed by SAP memory and ledger primitives. ## Tools - `sap_session_start` - `sap_session_read_latest` - `sap_sessi
# SAP Ledger Session
Use this skill for higher-level session continuity workflows backed by SAP
memory and ledger primitives.
## Tools
- `sap_session_start`
- `sap_session_read_latest`
- `sap_session_status`
- `sap_fetch_session`
- `sap_fetch_epoch_page`
## Flow
1. Start with `sap_session_status` when a session identifier is available.
2. Use `sap_session_start` to create or resume durable session context.
3. Use `sap_session_read_latest` before appending new context.
4. Use `sap_fetch_epoch_page` for finalized historical pages.
## Safety
Session storage is durable. Summarize sensitive context rather than storing raw
secrets or private user data.# SAP Market Data Use this skill for token prices, price history, OHLCV, liquidity pools, trending assets, token metadata, and security/intelligence checks. ## Tools - `pyth_getPrice` - `pyth_getPr
# SAP Market Data
Use this skill for token prices, price history, OHLCV, liquidity pools,
trending assets, token metadata, and security/intelligence checks.
## Tools
- `pyth_getPrice`
- `pyth_getPriceHistory`
- `pyth_listPriceFeeds`
- `coingecko_getTokenPrice`
- `coingecko_getTokenInfo`
- `coingecko_getOHLCV`
- `coingecko_getPoolsByToken`
- `coingecko_getTrending`
- `coingecko_getTopGainersLosers`
- `jupiter_getPrice`
- `jupiter_getTokenInfo`
- `jupiter_searchTokens`
- `jupiter_getTokenList`
- `jupiter_programLabels`
- `jupiter_shield`
- `jupiter_getHoldings`
## Flow
1. Resolve token mints with `jupiter_searchTokens` when the user gives only a
ticker.
2. Use Pyth for oracle-style price feeds.
3. Use CoinGecko for market data, OHLCV, pools, trending, gainers, and losers.
4. Use `jupiter_shield` and `jupiter_getTokenInfo` for token risk context.
## Safety
Market data is informational. Do not treat it as financial advice, and do not
execute trades from market data without explicit user intent.# SAP MCP Use this skill when an agent needs to operate the SAP MCP server through MCP, configure local or remote launch, inspect the loaded profile, or reason about safe signing behavior. ## First
# SAP MCP
Use this skill when an agent needs to operate the SAP MCP server through MCP,
configure local or remote launch, inspect the loaded profile, or reason about
safe signing behavior.
## First Step
If the user says "Start SAP MCP", "Initialize SAP MCP", "Load SAP", or "SAP
mode", treat it as the activation command. Call `sap_agent_start` when it is
available, then call `sap_agent_runtime_status` with the closest intent and
`sap_skills_bundle` with `includeContents: true`. Load the returned SAP MCP
skill contents into context before selecting advanced tools.
Always inspect runtime context through MCP tools, not by reading config files:
1. `sap_agent_start`
2. `sap_agent_runtime_status` with `intent: "connection"`, `"paid-call"`, `"registry-write"`, `"transaction-finalize"`, `"escrow"`, `"identity"`, or `"general"`
3. `sap_agent_context` for free compact agent/directory orientation before paid discovery
4. `sap_skills_bundle` with `includeContents: true`
5. `sap_pricing_catalog` before estimating hosted paid call tiers
6. `sap_agent_next_action` before retrying after any SAP MCP error or partial write result
7. `sap_skills_upgrade_plan` when local skills are missing or stale
8. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
9. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
10. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
11. `sap_profile_current`
12. `sap_profile_list`
13. `sap_profile_public_key`
14. `sap_network_stats`
For simple "are you connected?" checks, do not dump tool counts or inspect
local files. Use `sap_agent_runtime_status` first and answer with the hosted
endpoint, accountless/non-custodial model, local bridge readiness if visible,
and the next exact action.
The server profile is the source of truth. Environment variables from the MCP
client must not override profile-owned RPC or wallet settings unless
`SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE=true`.
## Response Language
Answer in the same natural language as the user's latest request. If the user
asks in English, answer in English even when previous chat history, tool output,
or repository docs contain Italian. Keep tool names, protocol IDs, addresses,
and error strings unchanged.
## Discovery Rules
- Use free exact/base reads first when the wallet, PDA, or a small orientation
page is enough: `sap_agent_context`, `sap_get_agent`, `sap_get_agent_profile`,
`sap_get_agent_stats`, `sap_is_agent_active`, `sap_get_global_state`, and
`sap_list_agents` with `limit <= 20`, `view: "compact"`, and
`includeProtocolIndexes: false`.
- Use `sap_get_network_overview` for live ecosystem counters.
- Use `sap_discover_agents` for targeted paid hosted discovery. Prefer
`query`, `wallet`, `agentPda`, `protocol`, `capability`, `capabilities`,
`hasX402Endpoint`, and small `limit` values before broad scans.
- Use `sap_list_all_agents` when the user asks for all current SAP ecosystem
agents. It performs global on-chain `AgentAccount` enumeration and returns
`pagination.nextCursor` when more pages are available.
- Use `sap_list_agents` for a free compact orientation page first. Larger
pages, `view: "full"`, hydration, protocol index summaries, and global scans
are paid read-premium.
- Use `sap_fetch_protocol_index` when a specific protocol ID is known.
- If a capability lookup returns zero results, retry with `query` or `wallet`
before saying an agent is absent. AgentAccount rows are canonical; indexes can
lag.
- Do not tell the user that all-agent enumeration is impossible unless
`sap_list_all_agents` fails and you report the exact failure.
## Tool Name Prefixes
Some MCP clients display SAP tools as `mcp_sap_<tool>`. The callable tool name
inside this server omits the client prefix. Example: a client may display
`mcp_sap_jupiter_getQuote`, while the MCP tool name is `jupiter_getQuote`.
## Upstream References
Use these official upstream references for the latest SAP SDK documentation and
source skill taxonomy:
- Synapse SAP SDK docs: https://github.com/OOBE-PROTOCOL/synapse-sap-sdk/tree/main/docs
- Synapse SAP SDK skills: https://github.com/OOBE-PROTOCOL/synapse-sap-sdk/tree/main/skills
Use the bundled routing map for local MCP tool selection:
- `skills/sap-mcp/TOOL_REFERENCE.md`
- `USER_DOCS/05_SKILLS_AND_TOOLS.md`
SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
`sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
`sap_agent_next_action`, `sap_pricing_catalog`,
`sap_skills_list`, `sap_skills_bundle`, `sap_skills_upgrade_plan`,
`sap_runtime_repair_plan`, and local `sap_skills_install` directly. Do not
route startup, runtime status, pricing catalog, skill listing, bundling,
upgrade planning, runtime repair planning, or installation through
`sap_x402_paid_call` or `sap_payments_call_paid_tool`. On hosted remote MCP, use
`sap_skills_bundle` to download skill contents; the hosted server cannot
install files onto the caller's local machine. Local installation belongs to the
wizard, desktop app, addon installer, or a local stdio SAP MCP process.
If skills or runtime bridge config are stale, call `sap_skills_upgrade_plan` or
`sap_runtime_repair_plan` first. These tools return the pinned latest-release
commands and preserve the non-custodial local signing model.
## Hosted Remote MCP
Canonical hosted endpoint:
```text
https://mcp.sap.oobeprotocol.ai/mcp
```
Public server metadata:
```json
{
"name": "sap-mcp-server",
"title": "SAP MCP Server | OOBE Protocol",
"status": "online",
"protocol": {
"primary": "mcp",
"transport": "streamable-http",
"protocolVersion": "2025-06-18"
},
"endpoints": {
"landing": "https://mcp.sap.oobeprotocol.ai/",
"mcp": "https://mcp.sap.oobeprotocol.ai/mcp",
"serverInfo": "https://mcp.sap.oobeprotocol.ai/server.json",
"wizardDescriptor": "https://mcp.sap.oobeprotocol.ai/.well-known/sap-mcp-wizard.json",
"wizardInstallScript": "https://mcp.sap.oobeprotocol.ai/wizard/install.sh"
},
"authentication": {
"schemes": ["none", "x402"],
"bearerRequired": false
},
"security": {
"keypairBytesExposed": false,
"storesUserKeypairs": false,
"rpcSecretsExposed": false,
"wizardConfigDirectory": "~/.config/mcp-sap"
}
}
```
Hosted users still need a local SAP MCP profile when they sign x402/pay.sh
payments, SAP transactions, Solana transactions, SNS operations, or settlement
actions. The hosted MCP server is not a wallet custodian.
For hosted paid tools, use the native x402 flow. If the client runtime cannot
attach `PAYMENT-SIGNATURE` itself, use the local SAP MCP `sap_payments` bridge.
Call `sap_agent_runtime_status` first for routing, then
`sap_payments_readiness` to verify the active profile, signer, SOL/USDC
balance, policy limits, and bridge status. Then call `sap_payments_call_paid_tool`
for the hosted paid tool. This is not a separate hosted signing plugin: it is
the local SAP MCP process using the user's configured SAP profile wallet or
external signer to sign the x402 payment payload, retry the hosted tool call,
and return the receipt.
`sap_x402_paid_call` is a backward-compatible alias only for older runtime
snippets. Neither helper must be treated as a remote hosted signing service.
When connected to hosted SAP MCP, `signerConfigured: false` on the remote
server means the hosted server is non-custodial. It does not mean the remote
tool surface is unavailable. Do not silently switch to local stdio just because
a hosted call requires x402 payment or because the hosted server does not hold
the user's signer. Use the hosted x402 flow first; ask the user before using a
local stdio fallback.
Hosted remote is accountless. If `sap_profile_current` returns
`accountModel: hosted-remote-accountless`, do not describe `default` as the
user's profile and do not infer the user's wallet from the hosted server. To
inspect the local user profile, wallet, signer status, and payment policy, call
the local `sap_payments.sap_payments_readiness` bridge when it is configured.
Use `sap_payments.sap_payments_profile_current` only as a narrower compatibility
profile check.
Basic wallet reads are free on hosted SAP MCP. Call `sol_get_balance`,
`spl-token_getBalance`, and `spl-token_getTokenAccounts` directly on the hosted
server. Do not send these balance checks through `sap_payments_call_paid_tool`,
and do not summarize a balance read as a facilitator `BlockhashNotFound`
problem unless a paid tool actually returned that error.
If a hosted paid tool returns `BlockhashNotFound`,
`transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
behind`, `minimum context slot`, `fetch failed`, `gateway timeout`, or a
response marked `retryable: true`, treat it as a transient x402/Solana RPC
settlement error. Do not claim that SAP MCP is down unless `/health` also
fails. Do not bypass the paid hosted path with terminal/direct RPC. Retry
through the local `sap_payments_call_paid_tool` bridge with the same tool name
and arguments, `confirm: true`, and `maxAttempts: 5` so a fresh payment payload
is created. Use `sap_x402_paid_call` only when a runtime still exposes the
legacy alias.
When a hosted paid/write builder returns `transactionBase64`, `transaction`, or
another unsigned Solana transaction payload, finalize it locally with
`sap_payments_finalize_transaction`. Do not call hosted `sap_sign_transaction`
for a user-owned signer, do not create `.js`/`.mjs` signing scripts, and do not
read keypair JSON.
If hosted SAP MCP returns `hosted_local_signer_required`, no x402 payment was
charged. The tool requires a local user signature or has no hosted unsigned
builder yet. For `sap_register_agent`, call
`sap_payments.sap_payments_register_agent` with the same registration fields and
`confirm: true`; it runs the SAP registry write through the local signer bridge
without charging a hosted x402 access fee. For `sap_update_agent`, call
`sap_payments.sap_payments_update_agent` with the intended replacement fields
and `confirm: true`; use it for public agent image/profile metadata updates via
`agentUri` or `metadataUri`. For Escrow V2, call the matching
`sap_escrow_build_*_transaction` hosted builder and finalize with
`sap_payments_finalize_transaction`. For other direct writes, do not retry the
same hosted tool; use the local SAP MCP profile or an unsigned hosted builder
plus `sap_payments_finalize_transaction` when one exists.
For registry lifecycle completion, do not treat a transaction signature alone
as enough. After `sap_payments_register_agent`, verify `success`,
`agentRegistered`, `agentPda`, `confirmationStatus`, `protocolComplete`, and
the returned `protocolFee.status`. `success: true` means both the agent account
and protocol fee invariant were verified. If `success` is false while
`agentRegistered` is true, report that the account may exist but the SAP
protocol registration lifecycle is not complete. After
`sap_payments_update_agent`, fetch the agent again and confirm the changed
fields before saying an image, metadata, pricing, or capability update is done.
Before any write-like operation, use this routing order:
1. Hosted read or paid hosted read: direct hosted tool, or
`sap_payments_call_paid_tool` when x402 is required.
2. Hosted unsigned transaction builder: finalize with
`sap_payments_finalize_transaction` and `submit: true` when the user confirms.
3. SAP registry registration/update: use `sap_payments_register_agent` or
`sap_payments_update_agent`; do not retry hosted accountless writes.
4. External x402 HTTP provider: use `sap_payments_call_external_x402`.
5. Missing bridge: call `sap_runtime_repair_plan`, then tell the user to run the
pinned repair command or desktop wizard repair path.
When summarizing a hosted connection, use language like:
"server is non-custodial; user signatures come from the local SAP profile or
external signer." Avoid saying "signer not configured", "read-only only",
"writes unavailable", or "remote MCP broken" unless a specific tool returns
that exact operational error.
For simple connection questions such as "are you connected to SAP MCP?", answer
briefly. Include connected yes/no, endpoint, mode, non-custodial status, and
one next action. Do not dump the full tool catalog, protocol list, or category
summary unless the user explicitly asks what tools are available. Startup logs
or registration logs prove that the MCP server started; they do not prove that
the current agent runtime injected every tool as callable. If `tools/list`
works but callable functions are missing, report a runtime reload/injection
issue and ask the user to restart the runtime.
If `sap_payments` tools are missing after the user says the wizard completed,
call `sap_runtime_repair_plan`. Do not ask the user to manually rebuild their
runtime config unless the repair plan has already failed or runtime startup logs
show a concrete package/runtime error.
For agent identity work, load the matching focused skills before acting:
- register, update, profile image, capability, pricing, or x402 endpoint:
`sap-agent-registry`
- NFT-backed identity, MPL Core, Metaplex metadata, creator/collection flows:
`sap-nft-metaplex`
- `.sol` domain ownership, records, or primary identity:
`sap-sns`
The canonical field and pipeline reference is
`docs/16_SAP_AGENT_IDENTITY_PIPELINE.md`. Follow it before registry writes.
## Profile Tools
| Tool | Purpose |
| --- | --- |
| `sap_profile_current` | Show loaded profile, active profile, RPC, network, program, signer public key |
| `sap_profile_list` | List available profiles without exposing wallet paths |
| `sap_profile_public_key` | Show profile agent public key |
| `sap_profile_switch` | Reload runtime to another profile; requires `confirm: true` |
## Wizard And CLI
Create or update a profile:
```bash
npx sap-mcp-wizard
# or
npx sap-mcp-config wizard
```
### `npx sap-mcp-config` Usage
Use `sap-mcp-config` for all local profile and wallet configuration. Do not
edit generated JSON files manually unless you are repairing a broken profile.
Recommended first setup:
```bash
npx sap-mcp-config wizard
```
The wizard creates `~/.config/mcp-sap/`, stores profile configs as
`config-<profile>.json`, and creates or links dedicated keypairs under the SAP
MCP config directory. It must not use or overwrite the Solana CLI keypair unless
the user explicitly chooses that path.
Show the currently loaded/active config:
```bash
npx sap-mcp-config show
npx sap-mcp-config info
```
List, inspect, and switch profiles:
```bash
npx sap-mcp-config profiles
npx sap-mcp-config profile-info
npx sap-mcp-config profile <profile-name>
```
Show the public agent identity:
```bash
npx sap-mcp-config pubkey
```
Check wallet status without printing keypair bytes:
```bash
npx sap-mcp-config wallet
```
Update safe scalar settings:
```bash
npx sap-mcp-config set rpcUrl https://api.mainnet-beta.solana.com
npx sap-mcp-config set logLevel info
npx sap-mcp-config set maxTxValueSol 10
npx sap-mcp-config set requireApprovalAboveSol 1
npx sap-mcp-config set dailyLimitSol 100
```
MCP client configuration should prefer the dynamic profile manager over
duplicated RPC or wallet env vars. In dynamic mode the server reads
`~/.config/mcp-sap/.active-profile`, so the user can change profile with
`sap-mcp-config profile <name>` and then restart the MCP client:
```yaml
mcp_servers:
sap:
command: node
args:
- /absolute/path/to/sap-mcp-server/dist/cli.js
cwd: /absolute/path/to/sap-mcp-server
env:
SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE: "false"
SAP_LOG_LEVEL: info
```
Only pin a fixed profile when that is intentional:
```yaml
env:
SAP_MCP_PROFILE: gianni-market-nft-agent
SAP_MCP_CONFIG_PATH: ~/.config/mcp-sap/config-gianni-market-nft-agent.json
SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE: "false"
SAP_LOG_LEVEL: info
```
Avoid passing `SAP_WALLET_PATH` or `SAP_MCP_RPC_URL` from the MCP client unless
the user intentionally wants env overrides and has set
`SAP_MCP_ALLOW_ENV_CONFIG_OVERRIDE=true`.
Hosted Claude/Codex/OpenClaw-style JSON:
```json
{
"mcpServers": {
"sap": {
"url": "https://mcp.sap.oobeprotocol.ai/mcp",
"transport": "streamable-http"
}
}
}
```
Hosted Hermes global `~/.hermes/mcp.json` JSON:
```json
{
"sap": {
"url": "https://mcp.sap.oobeprotocol.ai/mcp",
"transport": "streamable-http"
}
}
```
Hosted Hermes profile YAML:
```yaml
mcp_servers:
sap:
url: https://mcp.sap.oobeprotocol.ai/mcp
transport: streamable-http
```
Show active profile:
```bash
npx sap-mcp-config show
npx sap-mcp-config profile-info
npx sap-mcp-config pubkey
```
List and switch profiles:
```bash
npx sap-mcp-config profiles
npx sap-mcp-config profile <name>
```
Start local MCP over stdio:
```bash
npx sap-mcp-server start
```
Operator-only: start your own remote MCP over Streamable HTTP:
```bash
SAP_MCP_AUTH_TYPE=api_key \
SAP_MCP_API_KEYS=<api-key>=<operator-id> \
npx sap-mcp-remote
```
Do not ask hosted users to run their own HTTP server unless they are deploying
their own VPS/operator instance.
Do not call a local free `stdio` SAP MCP server as an implicit substitute for
hosted paid tools. Local stdio is a developer fallback only when the user asks
for local execution or the client cannot perform remote Streamable HTTP/x402.
## Signing Rules
- Do not read wallet/keypair files.
- Do not ask the user to paste private key bytes.
- Use `sap_preview_transaction` before any signing.
- Use `sap_sign_transaction` only after preview and policy checks.
- Use `sap_submit_signed_transaction` only for a signed transaction that the
user or policy explicitly allows.
- If a transaction exceeds policy limits, stop and ask the user for approval
through the surrounding agent UI.
## MCP Tool Reference
See `TOOL_REFERENCE.md` in this skill directory for the SAP tool mapping to
the most specific SAP skill domain. Use live `tools/list` for the exact runtime
count because upstream SDK tool registries can evolve.# SAP Memory Vault Use this skill for encrypted SAP memory vaults, vault sessions, memory inscriptions, compact inscriptions, and vault/session reads. ## Tools - `sap_init_vault` - `sap_fetch_vault
# SAP Memory Vault
Use this skill for encrypted SAP memory vaults, vault sessions, memory
inscriptions, compact inscriptions, and vault/session reads.
## Tools
- `sap_init_vault`
- `sap_fetch_vault`
- `sap_open_vault_session`
- `sap_fetch_session`
- `sap_inscribe_memory`
- `sap_compact_inscribe_memory`
- `sap_fetch_epoch_page`
## Flow
1. Use `sap_fetch_vault` to check whether the agent already has a vault.
2. Use `sap_init_vault` only when a vault is missing and the user wants durable
memory.
3. Use `sap_open_vault_session` before session inscriptions.
4. Use `sap_inscribe_memory` for normal entries and
`sap_compact_inscribe_memory` for compact payloads.
5. Use `sap_fetch_epoch_page` for finalized pages.
## Safety
Do not store private keys, seed phrases, wallet bytes, API keys, or raw secrets
in SAP memory.# SAP NFT And Metaplex Use this skill for NFT assets, collections, Metaplex minting, metadata, royalties, creator verification, authority delegation, and 3.Land marketplace flows. ## Tools - `das_g
# SAP NFT And Metaplex
Use this skill for NFT assets, collections, Metaplex minting, metadata,
royalties, creator verification, authority delegation, and 3.Land marketplace
flows.
## Tools
- `das_getAsset`
- `das_getAssetsByOwner`
- `das_getAssetsByCreator`
- `das_getAssetsByCollection`
- `das_searchAssets`
- `3land_createCollection`
- `3land_mintAndList`
- `3land_listForSale`
- `3land_cancelListing`
- `3land_buyNFT`
- `metaplex-nft_deployCollection`
- `metaplex-nft_mintNFT`
- `metaplex-nft_updateMetadata`
- `metaplex-nft_configureRoyalties`
- `metaplex-nft_setAndVerifyCollection`
- `metaplex-nft_verifyCollection`
- `metaplex-nft_verifyCreator`
- `metaplex-nft_delegateAuthority`
- `metaplex-nft_revokeAuthority`
## Flow
1. Use DAS read tools before write tools.
2. Validate collection, creator, metadata URI, royalties, and authority.
3. Preview transaction-producing outputs before signing.
## SAP Bridged Identity
When the user wants an SAP agent picture, NFT-backed identity, MPL Core asset,
or Metaplex-linked profile:
1. Publish the image and metadata to a public URI. Desktop file paths are never
valid on-chain metadata.
2. If creating a Metaplex NFT/MPL Core identity asset, mint or update that asset
with the same public metadata and keep the owner/authority clear.
3. Register or update the SAP agent with `metadataUri`/`agentUri` pointing to
the public metadata document or profile page.
4. In the metadata JSON, include a `metaplex` object with the asset or
collection address when available.
5. Hosted users must use local `sap_payments_register_agent` or
`sap_payments_update_agent` for SAP registry writes. Do not call hosted
`sap_register_agent` or hosted `sap_update_agent` after
`hosted_local_signer_required`.
Load `sap-agent-registry` together with this skill when the user says “register
my agent”, “add my picture”, “link my NFT identity”, or “bridge SAP with
Metaplex”.
## Safety
Minting, listing, buying, authority changes, and metadata updates are high-risk.
Never assume a collection or creator is trusted without verification.# SAP Operations Use this skill for SAP Protocol registry, agent lifecycle, memory, reputation, x402 payments, escrow, settlement, disputes, staking, and tool publishing. This skill corresponds to u
# SAP Operations
Use this skill for SAP Protocol registry, agent lifecycle, memory, reputation,
x402 payments, escrow, settlement, disputes, staking, and tool publishing.
This skill corresponds to upstream SAP SDK v1.0.x domains such as
`sap-overview`, `sap-client`, `sap-advanced`, `sap-memory`,
`sap-merchant`, and `sap-enterprise`.
## Operating Pattern
1. Inspect `sap_profile_current`.
2. Use read tools before write tools.
3. For write operations, explain the on-chain action and expected cost.
4. For transactions or direct signing, preview first with `sap_preview_transaction`.
5. Never read keypair files.
## Agent Registry
Use:
- `sap_protocol_invariants`
- `sap_agent_identity_plan`
- `sap_register_agent`
- `sap_update_agent`
- `sap_deactivate_agent`
- `sap_reactivate_agent`
- `sap_close_agent`
- `sap_get_agent`
- `sap_get_agent_profile`
- `sap_discover_agents`
- `sap_list_agents`
- `sap_list_all_agents`
Use `sap_discover_agents` for targeted hosted directory reads by `query`,
`wallet`, `agentPda`, `protocol`, `capability`, `capabilities`, or
`hasX402Endpoint`. Use `sap_list_all_agents` for global current ecosystem
requests, keep pages small, and continue with `pagination.nextCursor`.
For first-pass orientation, prefer free reads: `sap_agent_context`,
`sap_get_agent`, `sap_get_agent_profile`, `sap_get_agent_stats`,
`sap_is_agent_active`, `sap_get_global_state`, and `sap_list_agents` with `limit <= 20`,
`view: "compact"`, and `includeProtocolIndexes: false`. Use paid discovery
only when the user needs search, enrichment, full rows, large pages, analytics,
or global enumeration beyond the compact page.
Before registering or updating an agent profile, call free
`sap_protocol_invariants` when treasury, registration fee, hosted write route,
or local signer route is unclear. Then call `sap_agent_identity_plan`. The
planner tells the agent which fields are missing, whether the action should use
hosted reads or local signing, whether Metaplex or SNS identity is involved,
and how to verify the write afterward.
Hosted accountless SAP MCP cannot sign wallet-owned registry writes. If hosted
`sap_register_agent` or `sap_update_agent` returns
`hosted_local_signer_required`, do not retry the hosted write. Use local
`sap_payments_register_agent` or `sap_payments_update_agent` with
`confirm: true`. After registration, verify `success`, `agentPda`,
`confirmationStatus`, and `protocolFee.status`; after update, fetch the agent
profile again and compare the changed fields.
If any SAP operation returns `payment_required`, `hosted_local_signer_required`,
`BlockhashNotFound`, timeout, missing `sap_payments`, or a submitted signature
that did not confirm, call `sap_agent_next_action` before retrying. Follow its
`safeToRetryNow` and `nextTool` fields.
## Memory
Use:
- `sap_init_vault`
- `sap_fetch_vault`
- `sap_open_vault_session`
- `sap_fetch_session`
- `sap_inscribe_memory`
- `sap_compact_inscribe_memory`
- `sap_session_start`
- `sap_session_read_latest`
- `sap_session_status`
## Reputation And Attestations
Use:
- `sap_fetch_feedback`
- `sap_give_feedback`
- `sap_update_feedback`
- `sap_revoke_feedback`
- `sap_fetch_attestation`
- `sap_create_attestation`
- `sap_revoke_attestation`
- `sap_update_reputation_metrics`
- `sap_fairscale_score`
- `sap_fairscale_trust_gate`
## Payments, Escrow, Settlement
Use:
- `sap_x402_prepare_payment`
- `sap_x402_get_balance`
- `sap_create_subscription`
- `sap_fund_subscription`
- `sap_cancel_subscription`
- `sap_create_escrow_v2`
- `sap_deposit_escrow_v2`
- `sap_settle_escrow_v2`
- `sap_finalize_settlement_v2`
- `sap_file_dispute_v2`
- `sap_withdraw_escrow_v2`
- `sap_close_escrow_v2`
Escrow writes are V2-only. Default `settlementSecurity` is DisputeWindow (`2`);
CoSigned (`1`) requires `coSigner`; SelfReport (`0`) is not a valid default.
Escrow amounts are smallest token units: lamports for SOL and micro-USDC for
USDC.
## Staking
Use:
- `sap_init_stake`
- `sap_deposit_stake`
- `sap_request_unstake`
- `sap_complete_unstake`
- `sap_fetch_stake`# SAP Payments X402 Use this skill for SAP x402 payment context, balances, subscriptions, paid API workflows, and hosted SAP MCP x402/pay.sh monetization. ## Tools - `sap_x402_prepare_payment` - `s
# SAP Payments X402
Use this skill for SAP x402 payment context, balances, subscriptions, paid API
workflows, and hosted SAP MCP x402/pay.sh monetization.
## Tools
- `sap_x402_prepare_payment`
- `sap_x402_get_balance`
- `sap_payments_profile_current`
- `sap_payments_call_paid_tool`
- `sap_payments_call_external_x402`
- `sap_payments_register_agent`
- `sap_payments_update_agent`
- `sap_payments_finalize_transaction`
- `sap_payments_prepare_challenge`
- `sap_payments_sign_challenge`
- `sap_payments_verify_receipt`
- `sap_x402_paid_call`
- `sap_create_subscription`
- `sap_fund_subscription`
- `sap_cancel_subscription`
- `sap_fetch_subscription`
## Flow
1. Inspect agent profile and pricing with `sap_get_agent_profile`.
2. Use `sap_x402_prepare_payment` before building a paid request.
3. Use `sap_x402_get_balance` before assuming a depositor can pay.
4. Use subscription tools only after explaining amount, cadence, and
cancellation path.
## Hosted MCP Monetization
Canonical hosted endpoint: `https://mcp.sap.oobeprotocol.ai/mcp`.
Remote `/mcp` deployments can require x402 v2 payment for paid `tools/call`
requests. Local `stdio` usage remains free and should not attempt x402 payment.
Do not treat hosted `402 Payment Required` as a failure; it is the expected
payment handshake. Do not silently bypass hosted paid tools by switching to a
local free stdio MCP server unless the user explicitly asks for local execution.
If `sap_profile_current` says the hosted server has no signer, treat that as
the non-custodial model: OOBE does not hold user keys. Paid and value-moving
hosted calls still proceed through x402/pay.sh plus the user's local SAP profile
or external signer.
- Free: `tools/list`, `prompts/list`, `resources/list`, `sap_profile_current`,
`sap_agent_start`, `sap_agent_runtime_status`, `sap_agent_context`,
`sap_agent_next_action`, exact SAP agent/profile reads, compact
`sap_list_agents` pages with `limit <= 20`, `sap_get_network_overview`, `sol_get_balance`,
`spl-token_getBalance`, and `spl-token_getTokenAccounts`.
- Read premium: `sap_discover_agents`, `sap_list_all_agents`, full/enriched or
large `sap_list_agents` pages, indexed discovery, network stats,
protocol/capability indexes.
- Builder: batch SNS/domain checks, analytics, transaction builders.
- Value action: fixed fee plus configured basis-points fee when public USD
notional fields are present.
When a remote call returns HTTP `402`, read the x402 `PAYMENT-REQUIRED`
instructions, create a payment, retry with `PAYMENT-SIGNATURE`, and capture
`PAYMENT-RESPONSE` after settlement. If a `payShCheckoutUrl` is present, surface
it for browser/manual checkout flows.
Before retrying `payment_required`, `hosted_local_signer_required`,
`BlockhashNotFound`, timeout, missing `sap_payments`, or an unconfirmed
signature, call `sap_agent_next_action`. Use its `safeToRetryNow`, `nextTool`,
and `paymentCharged` fields as the retry guard.
For fast x402 execution:
1. Reuse the MCP session returned by `initialize`.
2. Retry the same MCP method and params after payment. The JSON-RPC `id` may
change, but the tool name and arguments must match the challenge.
3. Use `PAYMENT-SIGNATURE` first; use `X-PAYMENT` only for clients that require
the alternate header.
4. Cache free `tools/list`, `prompts/list`, and `resources/list` locally rather
than paying or re-fetching repeatedly.
5. Treat `PAYMENT-RESPONSE` as the receipt bound to the tool output.
6. If the client runtime cannot sign or attach x402 payment headers itself, use
the local SAP MCP `sap_payments_call_paid_tool` bridge configured by the SAP
MCP wizard instead of falling back to local stdio automatically.
Do not use x402 for basic balance reads. `sol_get_balance`,
`spl-token_getBalance`, and `spl-token_getTokenAccounts` are free hosted tools
and should be called directly through the remote SAP MCP connection.
When available locally, call `sap_payments_call_paid_tool` with `toolName`,
`arguments`, `maxPriceUsd`, and `confirm: true`. It initializes the hosted MCP
session, obtains the x402 challenge, signs with the user SAP MCP profile wallet
or external signer, retries the hosted tool call, and returns the settlement
receipt. Do not ask the user to install a separate x402 plugin when the local
SAP MCP `sap_payments` bridge is already configured. The legacy
`sap_x402_paid_call` alias is acceptable only when a runtime has not refreshed
to the new tool name.
For external x402 agents discovered through SAP registry metadata, do not
hand-roll HTTP payment scripts. Call `sap_payments_call_external_x402` with
`url`, `method`, optional JSON `body`, `maxPriceUsd`, `maxAttempts`, and
`confirm: true`. Use this for non-SAP-hosted HTTP providers such as another
agent's own x402 endpoint. It fetches the external 402 challenge, signs locally,
retries the same HTTP request with `PAYMENT-SIGNATURE`, and returns the response
plus receipt without exposing keypair bytes.
For hosted-user SAP agent registration, do not retry hosted
`sap_register_agent` after `hosted_local_signer_required`. The hosted server is
accountless by design and cannot sign user-owned registry writes. Call local
`sap_payments_register_agent` with the same registration fields and
`confirm: true`; it uses the active local SAP MCP profile signer, submits the
SAP registry transaction locally, and does not charge a hosted x402 access fee.
After it returns, verify `success`, `agentRegistered`, `confirmationStatus`,
`agentPda`, `protocolComplete`, and `protocolFee.status`. The expected protocol
fee is `100000000` lamports to treasury
`J7PyZAGKvprCz4SQ5DKBLAHstJxgVqZcz6kguUoWpP7P`. `success: true` means the agent
account and protocol fee invariant were both verified. If `success` is false
while `agentRegistered` is true, the account may exist but registration is not
SAP protocol-complete; report that state and do not retry automatically.
For hosted-user SAP agent profile updates, do not retry hosted
`sap_update_agent` after `hosted_local_signer_required`. Call local
`sap_payments_update_agent` with the intended replacement fields and
`confirm: true`; it signs locally and does not charge a hosted x402 access fee.
Use this for agent picture/profile metadata by first uploading the image or
metadata JSON to a public URI such as IPFS, Arweave, Kommodo, or HTTPS, then
setting `agentUri` or `metadataUri`. Do not use desktop file paths.
After update, fetch the agent profile again and verify the changed fields.
If the hosted paid tool returns `transactionBase64`, `transaction`, or an
unsigned transaction object, call `sap_payments_finalize_transaction` with
`confirm: true`. Set `submit: false` for preview/sign only, or `submit: true`
after the user approves execution. With `submit: true`, the bridge submits
already-signed bytes through `https://mcp.sap.oobeprotocol.ai/tx/submit` by
default and returns `confirmationStatus` plus `retrySafe`. Treat
`expired_or_not_landed` as unresolved, not success. Never create temporary
signing scripts, read keypair JSON, or call hosted `sap_sign_transaction` for
user-owned signatures.
For Escrow V2 hosted workflows, use the unsigned builder family first:
`sap_escrow_build_create_transaction`,
`sap_escrow_build_deposit_transaction`,
`sap_escrow_build_settle_transaction`,
`sap_escrow_build_finalize_transaction`,
`sap_escrow_build_withdraw_transaction`, or
`sap_escrow_build_close_transaction`, then finalize locally with
`sap_payments_finalize_transaction`. Use direct escrow write tools only when a
local SAP MCP profile with signer is the selected runtime.
Use low-level helpers only for custom clients:
- `sap_payments_prepare_challenge` returns the parsed hosted x402 challenge
without signing.
- `sap_payments_sign_challenge` signs a parsed challenge and returns a one-time
payment header. Treat that header as authorization material.
- `sap_payments_verify_receipt` decodes a `PAYMENT-RESPONSE` or
`X-PAYMENT-RESPONSE` receipt.
The OOBE hosted server should not expose local signing helpers when it has no
local user wallet because payment signing belongs on the user's machine.
## Transient Settlement Errors
If a hosted paid call fails with `BlockhashNotFound`,
`transaction_simulation_failed`, `smart_wallet_simulation_failed`, `node is
behind`, `minimum context slot`, `fetch failed`, `gateway timeout`, or a
response marked `retryable: true`, treat it as a transient x402/Solana RPC
settlement failure. Do not say the SAP MCP server is down unless `/health`
also fails. Do not switch to terminal/direct RPC to bypass payment, and do not
reuse the old signed payment payload.
Correct recovery:
1. Call the local `sap_payments_call_paid_tool` bridge again with the same
`toolName` and `arguments`.
2. Set `maxAttempts: 5` when the runtime supports it.
3. Let the helper create a fresh x402 challenge and payment payload for each
attempt.
4. If all attempts fail, report that x402 settlement is temporarily unavailable
and ask the user to retry or repair the facilitator/RPC deployment.
References: `USER_DOCS/03_PAYMENTS_X402_PAYSH.md` and
`docs/06_PAYMENTS_X402_AND_PAYSH.md`.
## Safety
Payment and subscription operations move funds or create future obligations.
Respect `maxTxValueSol`, `dailyLimitSol`, and `requireApprovalAboveSol`.
Do not log private key material, keypair bytes, or raw payment signatures.# SAP Reputation And Attestation Use this skill for feedback, reputation metrics, attestations, and FairScale trust scoring. ## Tools - `sap_fetch_feedback` - `sap_give_feedback` - `sap_update_feed
# SAP Reputation And Attestation
Use this skill for feedback, reputation metrics, attestations, and FairScale
trust scoring.
## Tools
- `sap_fetch_feedback`
- `sap_give_feedback`
- `sap_update_feedback`
- `sap_revoke_feedback`
- `sap_fetch_attestation`
- `sap_create_attestation`
- `sap_revoke_attestation`
- `sap_update_reputation_metrics`
- `sap_fairscale_score`
- `sap_fairscale_trust_gate`
## Flow
1. Fetch agent context with `sap_get_agent_profile`.
2. Fetch existing feedback or attestation before writing.
3. Use `sap_fairscale_score` for scoring and `sap_fairscale_trust_gate` for
policy-style allow/block decisions.
4. Explain score, tag, attester, metadata hash, and expiry before writes.
## Safety
Feedback and attestations are trust-affecting actions. Do not create reputation
data without explicit user intent and evidence.# SAP SNS Use this skill when an agent needs Solana Name Service domains, records, wallet resolution, ownership checks, or linking a domain to a SAP agent. This skill is adapted from upstream `sns-s
# SAP SNS
Use this skill when an agent needs Solana Name Service domains, records,
wallet resolution, ownership checks, or linking a domain to a SAP agent.
This skill is adapted from upstream `sns-skill` plus SAP MCP's
`sap_sns_*` wrappers.
## Safe Flow
1. Check the loaded profile with `sap_profile_current`.
2. Check one domain availability for free with `sap_sns_check_domain`.
3. Validate records with `sap_sns_validate_records`.
4. For hosted record updates, build an unsigned transaction with
`sap_sns_build_manage_record_transaction`.
5. Preview and finalize hosted builder transactions locally with
`sap_payments_finalize_transaction`.
6. Register domains directly only from a local SAP MCP profile using
`sap_sns_register_agent_domain` after explicit user confirmation.
7. After SNS ownership or records are ready, update the SAP agent metadata with
`sap_payments_update_agent` so `metadataUri` references the `.sol` identity.
Hosted accountless SAP MCP cannot register a .sol domain directly because the
purchase requires the user wallet signature. If a hosted direct registration is
rejected with `hosted_local_signer_required`, no x402 payment was charged; switch
to the local profile flow instead of retrying the hosted write.
## Tools
- `sap_sns_check_domain`
- `sap_sns_batch_check_domains`
- `sap_sns_resolve_domain`
- `sap_sns_validate_records`
- `sap_sns_get_domain_records`
- `sap_sns_get_record`
- `sap_sns_resolve_wallet`
- `sap_sns_check_ownership`
- `sap_sns_get_domain_pda`
- `sap_sns_get_record_pda`
- `sap_sns_build_manage_record_transaction`
- `sap_sns_register_agent_domain`
- `sns_registerDomain`
- `sns_resolveDomain`
- `sns_reverseLookup`
- `alldomains_getOwnedDomains`
- `alldomains_registerDomain`
- `alldomains_resolveDomain`
## Guardrails
- Never assume mainnet/devnet; read the profile RPC first.
- Never read the local wallet file.
- `sap_sns_check_ownership` canonical field is `owner`; `wallet` is accepted as
an alias for agent ergonomics.
- Prefer build/preview/sign flows over direct register flows when the user
needs to review transaction details.
- Do not claim `sap_sns_build_register_domain_transaction` exists unless it is
returned by `tools/list`.
- Do not route hosted direct registration through x402; hosted accountless
servers reject local-signer writes before payment.
## SAP Agent Identity Link
For “use my .sol as my SAP identity”:
1. Resolve or check ownership with `sap_sns_resolve_wallet` and
`sap_sns_check_ownership`.
2. If a record must change from hosted mode, build the unsigned record
transaction and finalize with `sap_payments_finalize_transaction`.
3. Update the agent metadata JSON to include:
`{ "sns": { "domain": "name.sol" } }`.
4. Call local `sap_payments_update_agent` with the public `metadataUri` and
`confirm: true`.# SAP Social Gaming Use this skill for Solana Actions/Blinks, Gibwork bounties, and Send Arcade gaming flows. ## Tools - `blinks_getAction` - `blinks_executeAction` - `blinks_confirmAction` - `blin
# SAP Social Gaming
Use this skill for Solana Actions/Blinks, Gibwork bounties, and Send Arcade
gaming flows.
## Tools
- `blinks_getAction`
- `blinks_executeAction`
- `blinks_confirmAction`
- `blinks_buildActionUrl`
- `blinks_resolveBlinkUrl`
- `blinks_validateActionsJson`
- `gibwork_createBounty`
- `gibwork_listBounties`
- `gibwork_submitWork`
- `send-arcade_listGames`
- `send-arcade_playGame`
## Flow
1. Validate action URLs or `actions.json` before execution.
2. Read bounties/games before creating or paying.
3. Explain entry fees, bounty amounts, or transaction effects before write
tools.
## Safety
Bounties, games, and actions can spend funds or trigger arbitrary protocol
actions. Preview and require explicit user intent.# SAP Solana Token Use this skill for SOL balances, SPL token balances, token accounts, transfers, minting, burning, account close/freeze/thaw, and token security checks. ## Tools - `sol_get_balanc
# SAP Solana Token
Use this skill for SOL balances, SPL token balances, token accounts, transfers,
minting, burning, account close/freeze/thaw, and token security checks.
## Tools
- `sol_get_balance`
- `spl-token_getBalance`
- `spl-token_getTokenAccounts`
- `spl-token_transfer`
- `spl-token_transferSol`
- `spl-token_deployToken`
- `spl-token_mintTo`
- `spl-token_burn`
- `spl-token_closeAccount`
- `spl-token_freezeAccount`
- `spl-token_thawAccount`
- `spl-token_rugCheck`
## Flow
1. Read profile/network with `sap_profile_current`.
2. Read balances before transfers or mint/burn operations.
3. Use `spl-token_rugCheck` before interacting with unknown token mints.
4. Preview/sign transaction-producing outputs through SAP transaction tools
when a serialized transaction is involved.
## Safety
Transfers, minting, burning, freezing, thawing, and account closing are
high-risk. Do not execute without explicit user intent.# SAP Staking Use this skill for SAP stake initialization, deposits, unstake requests, complete unstake flows, and stake reads. ## Tools - `sap_init_stake` - `sap_deposit_stake` - `sap_request_unst
# SAP Staking
Use this skill for SAP stake initialization, deposits, unstake requests,
complete unstake flows, and stake reads.
## Tools
- `sap_init_stake`
- `sap_deposit_stake`
- `sap_request_unstake`
- `sap_complete_unstake`
- `sap_fetch_stake`
## Flow
1. Read `sap_fetch_stake` before write operations.
2. Use `sap_init_stake` only when no stake account exists.
3. Explain lockup, amount, and unstake timing before deposits or unstake
requests.
## Safety
Stake operations affect capital and trust guarantees. Respect local policy and
ask for explicit approval when thresholds require it.# SAP Tool Registry Use this skill for publishing, fetching, updating, deactivating, reactivating, and reporting SAP tool descriptors. ## Tools - `sap_publish_tool_by_name` - `sap_update_tool` - `s
# SAP Tool Registry
Use this skill for publishing, fetching, updating, deactivating, reactivating,
and reporting SAP tool descriptors.
## Tools
- `sap_publish_tool_by_name`
- `sap_update_tool`
- `sap_deactivate_tool`
- `sap_reactivate_tool`
- `sap_fetch_tool`
- `sap_report_tool_invocations`
- `sap_find_tools_by_category`
- `sap_get_tool_category_summary`
- `sap_fetch_tool_category_index`
## Flow
1. Inspect `sap_profile_current`.
2. For discovery, use `sap_find_tools_by_category` or `sap_fetch_tool`.
3. For publishing or updates, explain protocol ID, category, params, and schema
impact before calling the write tool.
4. Report invocations only after real usage has occurred.
## Safety
Tool registry writes affect on-chain discoverability. Do not publish placeholder
schemas, fake HTTP methods, or unverifiable descriptions.