Skip to main content
Bands are an MCP-server control. They govern which tools the LLM can see in an MCP session. The SDK and REST API do not have bands — they expose their full surface to whatever code holds the API key. For non-MCP integrations, scope at the agent-token / policy layer instead.
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*Signing and wallet management (MPC)
broadcast+ send_transactionSign and submit transactions to the blockchain
*Owner mode only - not registered in agent-mode sessions. Signing runs through MPC 2-of-2 (DKLS23): WalletSuite holds one key share, the customer holds the other, and both shares are required for every signature. No full private key ever exists anywhere. See Security Model. 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, 13 in agent mode (create_wallet, create_agent_api_key, and create_custom_policy are owner-only). 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=full13Sign and broadcast (policy-gated, agent mode)
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 sign transactions through MPC
  4. Add broadcast when you are ready to execute on-chain actions
Each step is a deliberate expansion, not an accident.