Skip to main content

​
MCP Server

The Unwall MCP server lets AI assistants like Claude, Cursor, and other MCP-compatible clients interact with your Unwall project directly — checking balances, sending payments, and making x402 API calls through natural language.

​
What Is MCP?

The Model Context Protocol (MCP) is an open standard that lets AI assistants use external tools. Instead of writing code to call APIs, your AI assistant can use MCP tools as native capabilities. For example, you can ask Claude “What’s my wallet balance?” and it will call the get_balance tool automatically.

​
Installation

No global install is needed. The MCP server runs via npx: 
npx @unwall/mcp-server

​
Claude Desktop Configuration

Add the following to your Claude Desktop configuration file (claude_desktop_config.json): 
{
  "mcpServers": {
    "unwall": {
      "command": "npx",
      "args": ["@unwall/mcp-server"],
      "env": {
        "UNWALL_API_KEY": "aw_live_your_key"
      }
    }
  }
}
On macOS, the Claude Desktop config file is located at ~/Library/Application Support/Claude/claude_desktop_config.json. On Windows, it is at %APPDATA%\Claude\claude_desktop_config.json.

​
Cursor / VS Code

Add the MCP server in your editor’s MCP settings. The configuration is the same JSON format: 
{
  "mcpServers": {
    "unwall": {
      "command": "npx",
      "args": ["@unwall/mcp-server"],
      "env": {
        "UNWALL_API_KEY": "aw_live_your_key"
      }
    }
  }
}

​
Available Tools

The MCP server exposes the following tools to your AI assistant:
ToolDescriptionAPI Equivalent
get_balanceCheck wallet balanceGET /v1/balance
list_transactionsView transaction historyGET /v1/transactions
payMake a payment (any rail)POST /v1/pay
get_usdc_deposit_addressGet funding addressGET /v1/stablecoin/address
send_paymentSend ACH payment (deprecated)POST /v1/payments
x402_payx402 API call (deprecated)POST /v1/x402/pay
send_usdcUSDC transfer (deprecated)POST /v1/usdc/transfer
The pay tool is the recommended way to make payments. It supports all three rails (x402, USDC transfer, fiat ACH) and auto-routes based on the recipient. The send_payment, x402_pay, and send_usdc tools are deprecated but still functional.

​
Environment Variables

VariableRequiredDefaultDescription
UNWALL_API_KEYYes—Your Unwall API token (aw_live_...)
UNWALL_BASE_URLNohttps://api.unwall.xyzAPI base URL (override for testing)

​
Example Usage

Here is an example conversation with Claude using the Unwall MCP server:
You: What’s my current wallet balance?Claude: Let me check your Unwall balance.Uses get_balance toolYour project has 5.00 USDC available ($5.00 USD equivalent) with no pending transactions.
You: Fetch the latest market data from https://api.example.com/v1/market using x402. Limit spending to 0.50 USDC.Claude: I’ll fetch the market data using an x402 payment.Uses pay tool with recipient “https://api.example.com/v1/market” and max_amount_usdc 500000The request completed successfully. The API charged 0.05 USDC plus a 0.001 USDC platform fee. Here’s the market data:
{"data": [{"symbol": "BTC", "price": 95420.50}, ...]}
You: Send 10 USDC to 0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18 for the vendor invoice.Claude: I’ll send 10 USDC to that address.Uses pay tool with recipient “0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18” and amount_usd 10.00Payment submitted. Transaction ID: tx_abc123. The transfer is processing on Base chain and should complete within a few minutes.

​
Token Permissions

The MCP server inherits the permissions of the API token you provide. Make sure your token has the permissions your AI assistant needs:
ActionRequired Permission
Check balance, view transactionsread
Send USDC or fiat paymentspay
Make x402 API callsx402
For most use cases, create a token with all three permissions: read, pay, and x402. If your assistant only needs to monitor balances, a read-only token is sufficient and more secure.

​
Next Steps

API Tokens

Learn about token permissions and security best practices.

x402 Protocol

Deep dive into how x402 payments work under the hood.