Skip to main content
Three surfaces: MCP server (agents), SDK (code), REST API (any language). All compose with the same MPC signing layer and share policy gates, audit trail, structured errors, input validation, secret isolation, and HTTPS enforcement. Bands are MCP-only.

​
System Context

┌──────────────────┐      ┌─────────────────────────┐      ┌────────────────────┐
│                  │      │                         │      │                    │
│   LLM / Agent    │─────▶│   WalletSuite MCP       │─────▶│  WalletSuite API   │
│  (Claude, GPT,   │ MCP  │   Server                │ HTTP │  (REST API)        │
│   custom agent)  │◀─────│                         │◀─────│                    │
│                  │      │                         │      │                    │
└──────────────────┘      └──────────┬──────────────┘      └────────┬───────────┘
                                     │                               │
                           ┌─────────▼──────────┐          ┌────────▼───────────┐
                           │  Signing Layer      │          │  Blockchain RPCs   │
                           │  MPC 2-of-2         │          │  (multi-chain)     │
                           │  (DKLS23)           │          │                    │
                           │                     │          │                    │
                           └────────────────────┘          └────────────────────┘
The MCP server orchestrates between the agent and the signing layer. Signing is 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.

​
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 hostLangChain / CrewAI process embedding; IDE clients (Claude 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
MPC2-of-2 DKLS23 share orchestration; co-signing service holds one share, customer holds the other; policy-gated threshold signing
TxCompilerConverts API prepare-sign responses into signing-ready unsigned transaction hex
MoonPayWidget URL builder for fiat on-ramp (prepare_onramp tool)
AuditTrailHash-chained JSONL log for sign and broadcast operations - tamper-evident, append-only

​
Boundary of Responsibility

ComponentOwnsDoes Not Own
MCP ServerTool schema, input validation, error mapping, transport, band filteringBlockchain interaction, caching, chain-specific tx construction
MPC SigningDKLS23 share orchestration, threshold signature, 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)

​
Signing Models

All three surfaces compose with the same MPC 2-of-2 (DKLS23) signing layer - see Key Management for the share model and custody. External BYO (KMS, HSM, multisig, custodian) remains available through the SDK; see Bring your own signer. One MCP-specific constraint applies to BYO: MCP can only prepare, not sign with an external signer, so set MCP_BANDS=read,prepare and route the unsigned payload to your signer outside the MCP session.

​
What the Server Does Not Do

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