Use the MCP Server

WDK CLI includes the wdk-mcp Model Context Protocol server. It exposes wallet operations as structured tools over stdio and routes wallet-dependent operations to the same local daemon used by the CLI.

Prepare A Wallet

Install WDK CLI with the command in Install. This guide deliberately uses a dedicated development wallet and Sepolia test funds; the general Get Started guide uses Ethereum mainnet.

If agent-dev is your first wallet, it becomes the default automatically:

wdk wallet create --name agent-dev --words 12
wdk wallet unlock --name agent-dev --ttl 5

Enter and confirm a strong, non-empty passphrase when the create command prompts, then record the generated seed phrase offline.

If another wallet is already the default, select agent-dev explicitly:

wdk wallet default --name agent-dev

Wallet-dependent MCP tools use the default wallet unless the request includes wallet. The wallet must be unlocked before those tools run.

The TTL is absolute from unlock; MCP activity does not extend it. Use a short TTL during development and lock the wallet when the session ends.

Configure An MCP Client

Choose one setup target:

wdk mcp setup --ai-tool claude-desktop

wdk mcp setup --ai-tool claude-code

wdk mcp setup --ai-tool openclaw

Setup checks whether the target appears to be installed, tests the MCP server when possible, and reports the restart action required by that client.

Verify one target:

wdk mcp verify-setup --ai-tool claude-desktop

List the configuration status of all three targets:

wdk mcp list

Remove a target configuration with:

wdk mcp remove --ai-tool claude-desktop

Replace claude-desktop with claude-code or openclaw as needed.

Other MCP Clients

wdk-mcp is a standard stdio MCP server. For clients that accept the common mcpServers JSON shape, add:

{
  "mcpServers": {
    "wdk-wallet": {
      "command": "wdk-mcp"
    }
  }
}

This configuration requires the client process to find wdk-mcp on its PATH. If the client uses a different configuration shape or does not inherit your shell PATH, configure a stdio server named wdk-wallet and point its command to the installed wdk-mcp executable.

Available MCP Tools

get_history needs indexer configuration. buy_crypto and sell_crypto need MoonPay configuration. See Configuration.

CLI Capabilities Not Exposed Over MCP

wdk-mcp registers only the nine tools listed above. Through this server, an agent can operate a wallet that a person has already unlocked, but it cannot call the CLI's wallet administration or persistent-configuration commands.

• Wallet administration: wdk wallet create, import, export, unlock, lock, delete, rename, and default. These commands create, import, or reveal seed material; confirm wallet ownership; change wallet identity or default selection; or control an unlock session. wdk wallet unlock is deliberately the human authorization moment, and wdk wallet lock ends that session.
• Persistent configuration: wdk config set and reset, wdk network create and delete, and wdk token add and delete. These commands change durable local configuration and remain user-driven decisions.

This is a boundary of the MCP tool surface, not an operating-system sandbox. An AI client with separate shell access is outside this boundary and may be able to invoke wdk directly.

Preview And Confirm Transfers

send_token defaults to dryRun: true. The recommended client workflow is:

1. Call send_token without dryRun, or with dryRun: true.
2. Show the network, token, recipient, amount, and estimated fee to the user.
3. Ask the user to confirm those exact values.
4. Call send_token with dryRun: false only after confirmation.

Example preview request:

{
  "network": "sepolia",
  "to": "<recipient-address>",
  "amount": "0.0001",
  "wallet": "agent-dev"
}

Example execution request after confirmation:

{
  "network": "sepolia",
  "to": "<recipient-address>",
  "amount": "0.0001",
  "wallet": "agent-dev",
  "dryRun": false
}

Security And Session Boundaries

• The AI client sends tool parameters to wdk-mcp; it does not send the wallet seed or passphrase as tool input.
• Wallet operations cross the local daemon endpoint. On Unix-like systems, owner-only socket permissions block other OS users, not other processes running as the wallet owner.
• An unlocked wallet behaves like a local hot wallet for the session. Read, signing, and send operations do not ask for the passphrase again.
• --ttl 0 disables automatic expiry for that wallet. Prefer a finite TTL.
• Prompts or client-side confirmation dialogs are not daemon authorization controls.

Read Security Model before exposing an unlocked wallet to an AI client or local automation.

Lock the wallet when the session is finished:

wdk wallet lock --name agent-dev

When To Use The MCP Toolkit

Use MCP Toolkit when you need to build and control an MCP server in application code, select individual WDK tools, or add custom tools.

Use the WDK CLI MCP server when you want the bundled tool set and local wallet daemon, with automated setup for Claude Desktop, Claude Code, and OpenClaw or manual stdio configuration for another MCP-compatible client.

Need Help?