Skip to main content
Tools outside the active band set are never registered in the MCP schema — the LLM cannot discover or call them. Bands are resolved once at server startup; there is no per-request override.

​
The 4 Bands

BandToolsWhat the Agent Can Do
read (default)get_balance, get_all_balances, get_price, get_fee_quote, resolve_asset, get_tx_status, get_tx_historyQuery balances, prices, fees, assets, transaction status
prepare+ prepare_transfer, prepare_serialized_unsigned_tx, prepare_onrampConstruct unsigned transaction payloads (no execution)
sign+ get_wallet_address, sign_transaction, create_wallet*, create_agent_api_key*, create_custom_policy*OWS local signing and wallet management
broadcast+ send_transactionSign and submit transactions to the blockchain
*Owner-mode only. See OWS Local Signing. Bands are cumulative — each level includes all tools from the levels above it.

​
Configuration

Set the MCP_BANDS environment variable:
ValueActive Bands
readread
read,prepareread + prepare
read,prepare,signread + prepare + sign
fullall 4 bands
The default is read. Start narrow, expand as needed. 
{
  "mcpServers": {
    "walletsuite": {
      "command": "npx",
      "args": ["-y", "@walletsuite/mcp-server"],
      "env": {
        "WALLETSUITE_API_KEY": "your-key",
        "MCP_BANDS": "read,prepare"
      }
    }
  }
}

​
How It Works

Agent sends tool call
  → MCP Server checks: is this tool in the active band set?
    → YES: execute the tool, return result
    → NO: tool does not exist in the schema — the agent never sees it
This is not runtime authorization. The tools literally do not exist in the MCP tool list. An agent configured with MCP_BANDS=read has 7 tools in its schema. An agent with MCP_BANDS=full has 16 tools in owner mode or 13 in agent mode — the three owner-only tools (create_wallet, create_custom_policy, create_agent_api_key) are not registered when the server runs in agent mode. There is nothing to bypass because the restricted tools were never registered.

​
Tool Annotations

Every tool carries advisory metadata that helps MCP clients categorize behavior:
BandRead-onlyDestructiveIdempotentOpen-world
readyesnoyesyes
preparenononoyes
signnonoyesno
broadcastnoyesnoyes
Read tools are safe and repeatable. Sign tools are idempotent because signing the same payload always produces the same signature. Broadcast tools are destructive because submitting a transaction to the blockchain cannot be undone once confirmed.

​
Multi-Agent Pattern

Run multiple MCP server instances with different band configurations to implement role-based access:
Agent RoleBand ConfigTools VisiblePurpose
Monitoring agentMCP_BANDS=read7Portfolio queries, price alerts
Treasury agentMCP_BANDS=read,prepare10Prepare transactions for review
Executor agentMCP_BANDS=full16 (owner) / 13 (agent)Sign and broadcast (policy-gated)
Each agent sees only the tools appropriate to its role. The executor agent’s signing is further constrained by Policy Gates — band filtering controls visibility, policies control behavior.

​
Feature-Gated Tools

Some tools within active bands may return not_available errors if the backend feature is not enabled for your API key (e.g., swaps, staking, NFTs). This is a separate layer:
  • Bands control the MCP tool schema (which tools exist)
  • Feature gates control the backend API (which tools succeed)
A tool gated by the backend returns a structured error with category: "not_available" and a message explaining why. See Structured Errors for how to handle these.

​
Why Start with Read

Read-only tools answer most wallet questions without creating transfer payloads or exposing any signing surface:
  • “What’s my ETH balance?” — get_balance
  • “How much is 1 ETH in USD?” — get_price
  • “What would the gas fee be for this transfer?” — get_fee_quote
  • “Show me recent transactions” — get_tx_history
A safe rollout pattern:
  1. Start with read — prove the integration works
  2. Add prepare when you need transaction construction
  3. Add sign when you are ready to manage a local OWS wallet
  4. Add broadcast when you are ready to execute on-chain actions
Each step is a deliberate expansion, not an accident.