@oobe-protocol-labs/sap-mcp-server 0.9.11 → 0.9.15

package/server.json

@@ -3,7 +3,7 @@
   "name": "ai.oobeprotocol.sap.mcp/sap-mcp",
   "title": "SAP MCP Server | OOBE Protocol",
   "description": "Solana-native MCP gateway for SAP tools, DeFi, SNS identity, x402/pay.sh, and agent operations.",
-  "version": "0.9.11",
+  "version": "0.9.15",
   "websiteUrl": "https://mcp.sap.oobeprotocol.ai/",
   "repository": {
     "url": "https://github.com/OOBE-PROTOCOL/sap-mcp",
@@ -29,7 +29,7 @@
     {
       "registryType": "npm",
       "identifier": "@oobe-protocol-labs/sap-mcp-server",
-      "version": "0.9.11",
+      "version": "0.9.15",
       "transport": {
         "type": "stdio"
       },
@@ -45,7 +45,7 @@
         },
         {
           "type": "positional",
-          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.11"
+          "value": "@oobe-protocol-labs/sap-mcp-server@0.9.15"
         },
         {
           "type": "positional",

package/skills/sap-agent-registry/SKILL.md

@@ -6,15 +6,23 @@ state, global directory listing, and agent profile inspection.
 ## First Steps
 
 1. Call `sap_profile_current`.
-2. Call `sap_get_network_overview` for ecosystem counters when needed.
-3. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
+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. Call `sap_get_network_overview` for ecosystem counters when needed.
+5. Use `sap_discover_agents` with `query`, `wallet`, `protocol`, or
    `capability` for targeted paid hosted directory reads.
-4. Use `sap_list_all_agents` for global current agent lists and follow
+6. 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_update_agent`
 - `sap_deactivate_agent`
 - `sap_reactivate_agent`
@@ -36,9 +44,29 @@ state, global directory listing, and agent profile inspection.
   `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 other registry writes, run the write on the local
-  SAP MCP profile or use a production unsigned builder/finalizer flow when
+  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.
+- 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
@@ -53,3 +81,33 @@ state, global directory listing, and agent profile inspection.
 
 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.

package/skills/sap-escrow-settlement/SKILL.md

@@ -7,6 +7,17 @@ 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`
@@ -26,13 +37,20 @@ recommend V1 create, deposit, settle, withdraw, close, or batch-settle flows.
 ## Flow
 
 1. Fetch V2 escrow state before mutating it.
-2. For V2 settlement, inspect pending settlement and dispute state.
-3. Explain amount, depositor, agent PDA, nonce, settlement index, and dispute
+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.
-4. Treat `settlementSecurity = 2` / DisputeWindow as the safe default.
+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`.
-5. Amounts are always in the smallest unit of the escrow token: lamports for
+7. Amounts are always in the smallest unit of the escrow token: lamports for
    SOL, micro-USDC for USDC.
 
 ## Safety

package/skills/sap-mcp/SKILL.md

@@ -8,19 +8,29 @@ safe signing behavior.
 
 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_skills_bundle` with `includeContents: true` and load
-the returned SAP MCP skill contents into context.
+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_skills_bundle` with `includeContents: true`
-3. `sap_skills_upgrade_plan` when local skills are missing or stale
-4. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
-5. `sap_profile_current`
-6. `sap_profile_list`
-7. `sap_profile_public_key`
-8. `sap_network_stats`
+2. `sap_agent_runtime_status` with `intent: "connection"`, `"paid-call"`, `"registry-write"`, `"transaction-finalize"`, `"escrow"`, `"identity"`, or `"general"`
+3. `sap_skills_bundle` with `includeContents: true`
+4. `sap_pricing_catalog` before estimating hosted paid call tiers
+5. `sap_skills_upgrade_plan` when local skills are missing or stale
+6. `sap_runtime_repair_plan` when hosted tools are connected but `sap_payments` is missing
+7. `sap_protocol_invariants` before SAP registry writes or when treasury, protocol fee, hosted write routing, or local signer routing is unclear
+8. `sap_agent_identity_plan` before agent registration, profile-image updates, Metaplex identity, SNS linking, or full identity setup
+9. `sap_profile_current`
+10. `sap_profile_list`
+11. `sap_profile_public_key`
+12. `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
@@ -70,11 +80,12 @@ Use the bundled routing map for local MCP tool selection:
 - `USER_DOCS/05_SKILLS_AND_TOOLS.md`
 
 SAP MCP startup and skill bootstrap tools are free context/setup tools. Call
-`sap_agent_start`, `sap_skills_list`, `sap_skills_bundle`,
-`sap_skills_upgrade_plan`, `sap_runtime_repair_plan`, and local
-`sap_skills_install` directly. Do not route startup, skill listing, bundling,
+`sap_agent_start`, `sap_agent_runtime_status`, `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`. On hosted remote MCP, use
+`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.
@@ -128,12 +139,13 @@ 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_payments_readiness` first 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.
+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.
 
@@ -180,9 +192,36 @@ 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 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.
+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
@@ -204,6 +243,18 @@ 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 |

package/skills/sap-mcp/TOOL_REFERENCE.md

@@ -37,7 +37,7 @@ Profile, config, runtime context, and raw transaction lifecycle:
 
 SAP registry and discovery:
 
-`sap_register_agent`, `sap_update_agent`, `sap_deactivate_agent`,
+`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_get_agent_stats`, `sap_get_global_state`,
 `sap_get_network_overview`, `sap_discover_agents`, `sap_list_agents`,
@@ -56,6 +56,14 @@ a list of all agents in the SAP ecosystem rn"; start with a small `limit` and
 continue with `pagination.nextCursor`. If a capability lookup returns zero,
 retry with `query` or `wallet` before reporting that the agent is absent.
 
+Use `sap_protocol_invariants` before registry writes when the program id,
+protocol treasury, source-level 0.1 SOL registration fee invariant, hosted
+write route, or local signer route is unclear. Use `sap_agent_identity_plan`
+before registration,
+profile/image updates, Metaplex identity bridging, SNS linking, or x402
+endpoint publishing. It is a free planner and should run before any local
+signer write.
+
 SAP memory and sessions:
 
 `sap_init_vault`, `sap_fetch_vault`, `sap_open_vault_session`,
@@ -75,6 +83,12 @@ SAP payments, x402, subscriptions, Escrow V2, settlement, disputes, staking:
 `sap_x402_prepare_payment`, `sap_x402_get_balance`,
 `sap_create_subscription`, `sap_fund_subscription`,
 `sap_cancel_subscription`, `sap_fetch_subscription`,
+`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`,
 `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`,
@@ -86,6 +100,13 @@ SAP payments, x402, subscriptions, Escrow V2, settlement, disputes, staking:
 Use `sap_fetch_escrow` only for legacy read-only inspection. V1 escrow write
 tools are not part of the active SAP MCP surface.
 
+In hosted mode, prefer `sap_escrow_build_*_transaction` for Escrow V2 writes
+and finalize the returned unsigned transaction locally with
+`sap_payments_finalize_transaction`. Use direct `sap_create_escrow_v2`,
+`sap_deposit_escrow_v2`, `sap_settle_escrow_v2`,
+`sap_finalize_settlement_v2`, `sap_withdraw_escrow_v2`, and
+`sap_close_escrow_v2` only when running a local SAP MCP profile with a signer.
+
 ## `sap-sns`
 
 SAP SNS and direct SNS domain workflows:

package/skills/sap-nft-metaplex/SKILL.md

@@ -32,6 +32,28 @@ flows.
 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.

package/skills/sap-operations/SKILL.md

@@ -19,6 +19,8 @@ This skill corresponds to upstream SAP SDK v1.0.x domains such as
 
 Use:
 
+- `sap_protocol_invariants`
+- `sap_agent_identity_plan`
 - `sap_register_agent`
 - `sap_update_agent`
 - `sap_deactivate_agent`
@@ -35,6 +37,21 @@ Use `sap_discover_agents` for targeted hosted directory reads by `query`,
 `hasX402Endpoint`. Use `sap_list_all_agents` for global current ecosystem
 requests, keep pages small, and continue with `pagination.nextCursor`.
 
+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.
+
 ## Memory
 
 Use:

package/skills/sap-payments-x402/SKILL.md

@@ -11,6 +11,7 @@ workflows, and hosted SAP MCP x402/pay.sh monetization.
 - `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`
@@ -98,12 +99,42 @@ 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. Never create temporary signing scripts, read
-keypair JSON, or call hosted `sap_sign_transaction` for user-owned signatures.
+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:
 

package/skills/sap-sns/SKILL.md

@@ -17,6 +17,8 @@ This skill is adapted from upstream `sns-skill` plus SAP MCP's
    `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
@@ -48,9 +50,24 @@ to the local profile flow instead of retrying the hosted write.
 
 - 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`.

package/smithery.config.schema.json

@@ -54,6 +54,13 @@
       "description": "Copy this command into a local terminal when paid/write tools should work from a non-custodial user profile.",
       "const": "npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard",
       "default": "npm exec --yes --package @oobe-protocol-labs/sap-mcp-server -- sap-mcp-config wizard"
+    },
+    "submitRelayUrl": {
+      "type": "string",
+      "title": "Signed transaction submit relay",
+      "description": "Optional submit-only relay for already-signed Solana transactions returned by local sap_payments_finalize_transaction. The relay never signs and never receives keypair bytes.",
+      "const": "https://mcp.sap.oobeprotocol.ai/tx/submit",
+      "default": "https://mcp.sap.oobeprotocol.ai/tx/submit"
     }
   }
 }