Skip to main content
By default:
  • OWS is disabled
  • signing tools are not exposed
  • broadcast tools are not exposed
When OWS is enabled, WalletSuite MCP remains non-custodial. Keys stay in the local OWS vault. OWS is the operator-side trust anchor for signing:
  • keys stay on the operator-controlled host
  • WalletSuite MCP never receives private keys
  • signing happens locally, with owner or policy-based control depending on mode

​
Vault location

By default, OWS uses this local vault path: 
~/.ows
To use a different vault directory, set: 
OWS_VAULT_PATH=/path/to/your/ows-vault
Use the same OWS_VAULT_PATH value for:
  • the WalletSuite MCP server process
  • the OWS agent bootstrap helper, if you use agent mode

​
Enable owner mode

Set:
OWS_ENABLED=true
OWS_VAULT_PATH=~/.ows
OWS_AUTH_MODE=owner
OWS_PASSPHRASE=your-passphrase
If you also want local broadcast with send_transaction, add the chain RPC URLs you need:
OWS_ETHEREUM_RPC_URL=https://...
OWS_TRON_RPC_URL=https://...

​
What tools appear

Owner mode can expose:
  • create_wallet
  • create_custom_policy — register a scoped OWS policy (chain allowlist + expiry)
  • create_agent_api_key — mint an agent token bound to a wallet and optional policy; token is written to a mode-0600 file and never returned in chat
  • get_wallet_address
  • sign_transaction
  • send_transaction when the broadcast band is enabled
create_wallet, create_custom_policy, and create_agent_api_key are owner-exclusive — they are not registered when the server runs in agent mode.

​
Create a wallet

After the server starts in owner mode, ask the MCP host:
Create a wallet called treasury
create_wallet creates a local OWS wallet, derives the supported addresses, and returns wallet metadata. It does not return the mnemonic or private keys.

​
Signing vs sending

Use sign_transaction when you want detached signing of a raw unsigned transaction hex blob.Use send_transaction only when:
  • the user has explicitly confirmed the transaction
  • you set confirmBroadcast=true
  • the matching chain RPC URL is configured
send_transaction is the destructive path because it broadcasts an on-chain transaction.

​
Policy controls

Owner mode is direct local control: the user unlocks the local vault and signs from that host.Agent mode is delegated local control: a pre-created OWS token is bound to the wallet and its policy.In the current default WalletSuite MCP setup, that policy gates agent-mode signing by:
  • allowed chains
  • an expiry window
If the request falls outside policy, OWS rejects the signing operation before the key is used.

​
Broadcast requirements

send_transaction only works when all of the following are true:
  • OWS is enabled
  • the broadcast band is active
  • confirmBroadcast=true is supplied
  • the matching RPC URL is set for the chain
  • the input is raw unsigned transaction hex

​
Verifying OWS status

When OWS is working, startup logs report one of these states:
  • disabled
  • owner mode
  • agent mode
If sign_transaction is missing from the visible tools, OWS is not enabled for that MCP instance or the active band set does not include sign.

​
Common issues

​
OWS_LOAD_FAILED or Failed to load @open-wallet-standard/core

The server dynamically imports @open-wallet-standard/core when OWS is enabled, and the import threw at runtime. Common causes: the package is not installed in the runtime’s node_modules, a platform-specific build artifact is missing or incompatible with the current Node.js / OS / architecture, or the dependency is being loaded from a stale install. Reinstall the MCP server (or the @open-wallet-standard/core dependency) on the target platform with Node.js 22 or newer and retry.

​
OWS_WALLET_EXISTS

The requested wallet name already exists in the local vault. Choose a different walletName or reuse the existing wallet.

​
OWS_WALLET_NOT_FOUND

The named wallet does not exist in the selected vault. Check walletName, verify OWS_VAULT_PATH, or create the wallet first in owner mode.

​
OWS_ACCOUNT_NOT_FOUND

The wallet exists, but it does not expose an account for the requested chain. Use a wallet with support for the selected OWS chain.

​
OWS_AGENT_TOKEN_EXPIRED

Regenerate the token, update OWS_AGENT_TOKEN, and restart the server.

​
OWS_AGENT_TOKEN_INVALID

The configured token does not exist in the vault. Generate a new agent token and update OWS_AGENT_TOKEN.

​
OWS_CREDENTIAL_INVALID

The passphrase or token does not match the vault. Double-check OWS_PASSPHRASE or OWS_AGENT_TOKEN.

​
OWS_POLICY_DENIED

The current OWS policy rejected the signing request. Use an allowed chain or generate a token with a policy that permits the operation.

​
OWS_INVALID_UNSIGNED_TX

The input is not valid raw unsigned transaction hex. Pass raw unsigned transaction hex to sign_transaction or send_transaction.

​
OWS_RPC_URL_REQUIRED

send_transaction was called without the matching RPC URL environment variable for the selected chain.

​
OWS_OWNER_MODE_REQUIRED

You tried to run an owner-only flow, such as wallet creation or agent-token bootstrap, while the server was configured for agent mode. Restart with OWS_AUTH_MODE=owner and OWS_PASSPHRASE.

​
OWS_OPERATION_FAILED

OWS returned a generic failure. Check server logs, verify the selected vault path and credentials, and retry with the simplest working flow first.

​
Signing tools are missing

Check:
  • OWS_ENABLED=true
  • MCP_BANDS includes sign
  • MCP_BANDS includes broadcast if you expect send_transaction