Skip to main content
WalletSuite is an intent-driven MCP server that translates natural language wallet requests into blockchain operations. It sits between AI models and the WalletSuite REST API, orchestrating queries, transaction preparation, and optional local signing.

​
System Context

┌──────────────────┐      ┌─────────────────────────┐      ┌────────────────────┐
│                  │      │                         │      │                    │
│   LLM / Agent    │─────▶│   WalletSuite MCP       │─────▶│  WalletSuite API   │
│  (Claude, GPT,   │ MCP  │   Server                │ HTTP │  (REST API)        │
│   custom agent)  │◀─────│                         │◀─────│                    │
│                  │      │                         │      │                    │
└──────────────────┘      └──────────┬──────────────┘      └────────┬───────────┘
                                     │                               │
                           ┌─────────▼──────────┐          ┌────────▼───────────┐
                           │  OWS Signing Layer  │          │  Blockchain RPCs   │
                           │  (optional)         │          │  (multi-chain)     │
                           │  Local keys,        │          │                    │
                           │  policy-gated       │          │                    │
                           └────────────────────┘          └────────────────────┘
The MCP server runs locally on the host that executes your agent runtime. It calls the WalletSuite REST API for blockchain data and transaction preparation. If OWS local signing is enabled, it also manages a local encrypted key vault for signing and broadcasting.

​
Design Principle

Every MCP tool maps to a user outcome, not a REST endpoint. The server orchestrates multiple API calls behind a single tool when needed. For example, a token transfer requires resolving the asset first, then preparing the transaction — the agent handles this as two clear steps, not raw API calls.

​
Component Layers

​
Transport Layer

Handles MCP protocol communication between the AI host and the server.
TransportHow It WorksWhen to Use
stdio (default)Runs as a child process of the MCP hostClaude Desktop, Claude Code, Cursor, VS Code
HTTP statelessEach request creates a new server instanceDocker, serverless, auto-scaling
HTTP statefulSessions persist via Mcp-Session-Id headerSSE streaming, resumable sessions
See Choose Your Setup for guidance on which transport to use.

​
Tool Handler Layer

Maps MCP tool calls to service operations. Each handler:
  1. Validates input using Zod schemas (address format, amount, chain)
  2. Calls the service layer
  3. Returns a structured MCP response or a structured error
Tools are organized by band — read, prepare, sign, broadcast. Only tools in the active band set are registered.

​
Service Layer

Shared business logic behind the tool handlers:
ServiceResponsibility
WalletSuiteApiClientTyped HTTP client for the REST API — retry, timeout, response envelope unwrapping
OWSLocal key generation, encrypted key storage, policy-gated signing
TxCompilerConverts API prepare-sign responses into signing-ready unsigned transaction hex
MoonPayWidget URL builder for fiat on-ramp (prepare_onramp tool)
AuditTrailAppend-only JSONL log for sign and broadcast operations

​
Boundary of Responsibility

ComponentOwnsDoes Not Own
MCP ServerTool schema, input validation, error mapping, transport, band filteringBlockchain interaction, caching, chain-specific tx construction
OWS SigningLocal key generation, encrypted storage, policy enforcement, sign and broadcastTransaction preparation, MCP protocol
WalletSuite APIChain interaction, fee estimation, tx simulation, broadcast, caching, volume trackingLLM integration, tool discovery, signing
You (integrator)LLM orchestration, user confirmation, wallet UIAPI orchestration, fee calculation (handled by API)

​
Two Signing Modes

​
External Signing (Default)

The MCP server prepares unsigned transaction payloads. You sign with your own wallet infrastructure (HSM, KMS, browser extension, or any signing solution). 
Agent → prepare_transfer → unsigned payload → your wallet signs → your infra broadcasts
Use MCP_BANDS=read,prepare. No OWS needed.

​
OWS Local Signing (Opt-In)

Keys generated and stored locally via the Open Wallet Standard. Policy-gated signing with chain allowlists and expiry. Keys never leave the device. 
Agent → prepare_serialized_unsigned_tx → sign_transaction (OWS) → send_transaction (OWS) → chain
Requires OWS_ENABLED=true. Band set depends on what you want: read,prepare,sign is enough for detached signing (sign_transaction); add broadcast (or use full) to also expose send_transaction. full is a convenience alias for all four bands, not a requirement for OWS. See OWS Local Signing.

​
What the Server Does Not Do

  • Store or transmit private keys
  • Cache blockchain data (the API backend handles caching)
  • Make signing decisions (OWS policy engine or the user decides)
  • Expose internal orchestration logic (tools map to outcomes, not implementation details)