AI Integration Overview

MCP Wallet enables secure AI assistant integration through OAuth 2.1 and the Model Context Protocol (MCP), allowing AI to help manage your crypto while you stay in control.

What is AI Integration?

AI integration allows AI assistants like Claude Code to interact with your wallet through a secure API:

• Check balances - "How much BNB do I have?"
• Send transactions - "Send 0.1 BNB to this address"
• View history - "What transactions did I make today?"
• Monitor status - "Is my transaction confirmed?"

How It Works

Architecture

┌─────────────────┐         OAuth 2.1          ┌──────────────┐
│  AI Assistant   │ ◄────────────────────────► │  MCP Wallet  │
│  (Claude Code)  │    MCP Protocol/JSON-RPC   │   (Tauri)    │
└─────────────────┘                             └──────────────┘
                                                       │
                                                       ▼
                                                ┌──────────────┐
                                                │  Blockchain  │
                                                │    (BSC)     │
                                                └──────────────┘

Flow

1. Authorization - AI requests access via OAuth 2.1
2. You Approve - You grant specific permissions in MCP Wallet (one-time)
3. Token Issued - AI receives time-limited access token
4. AI Requests - AI makes transaction requests via MCP protocol
5. Token Verify - Wallet verifies OAuth token is valid
6. Auto-Execute - Transactions executed automatically
7. Blockchain - Transaction broadcast to network

Security Model

Three Layers of Protection

Layer 1: OAuth 2.1 with PKCE

• Industry-standard authorization protocol
• PKCE (Proof Key for Code Exchange) prevents token interception
• Time-limited tokens (1 hour access, 30 days refresh)
• Revocable at any time by disabling API

Layer 2: Scoped Permissions

• wallet:read - View balances and addresses
• wallet:write - Modify account settings (limited)
• wallet:transaction - Send transactions

Layer 3: Transaction Monitoring

• All AI transactions labeled as "AI-initiated"
• Transaction history tracking
• User can disable API access anytime
• OAuth token revocation

What AI Can Do ✅

• Check balances for all tokens
• View wallet addresses
• View transaction history
• Send transactions (after user authorization)
• Check transaction status
• View network information

What AI Cannot Do ❌

• Access your password
• View your seed phrase
• Export private keys
• Modify security settings
• Delete accounts
• Change password
• Disable API access
• Continue after API is disabled

Supported AI Assistants

Currently Supported

Claude Code ✅

Status: Full support Integration: OAuth 2.1 + MCP Documentation: Claude Code Integration

Features:

• Balance checking
• Transaction sending
• Transaction monitoring
• Multi-token support

Example:

User: Send 0.1 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
Claude: I'll send 0.1 BNB to that address.
[Transaction sent successfully]

Gemini CLI ✅

Status: Full support Integration: OAuth 2.1 + MCP Documentation: Gemini CLI Integration

Features:

• Balance checking
• Transaction sending
• Transaction monitoring
• Multi-token support

Example:

> How much BNB do I have in my wallet?
You have 0.892 BNB in your wallet.

> Send 0.01 BNB to 0x742d35...
Transaction sent successfully!

Trae ✅

Status: Full support (via SSE Adapter) Integration: SSE Transport + OAuth Coordinator Documentation: SSE Transport Guide

Features:

• Balance checking
• Transaction sending
• Transaction monitoring
• Multi-token support
• One-time authorization (v2.0)

Note: Requires SSE Adapter v2.0 because Trae only supports the old MCP specification (2024-11-05) with SSE transport

Example:

> Check my BNB balance
You have 0.892 BNB in your wallet.

> Send 0.01 BNB to 0x742d35...
Transaction sent successfully!

Codebuddy ✅

Status: Full support Integration: OAuth 2.1 + MCP (HTTP Transport) Documentation: Codebuddy Integration

Features:

• Balance checking
• Transaction sending
• Transaction monitoring
• Code-integrated wallet access
• Multi-token support

Example:

> What's my wallet address?
Your wallet address is 0x742d35...

> Send 0.01 BNB to 0x742d35...
Transaction sent successfully!

Coming Soon

Cursor 🔜

Status: In development Expected: Q2 2025 Integration: OAuth 2.1 + MCP

Planned Features:

• Same capabilities as Claude Code
• IDE-integrated wallet management
• Code-generated transactions

GitHub Copilot 🔜

Status: Planned Expected: Q3 2025 Integration: OAuth 2.1 + MCP

Planned Features:

• GitHub integration
• Smart contract interactions
• Repository-based wallet management

Getting Started

Prerequisites

1. MCP Wallet installed - Installation Guide
2. Wallet created - Getting Started
3. Wallet unlocked - Must be unlocked for AI access
4. MCP Server running - Auto-starts when wallet unlocked

Quick Start

1. Enable API Access

   • Settings → Accounts → Enable API toggle

2. Configure AI Assistant

   • Add MCP Wallet server to AI config
   • See AI-specific guides:
     • Claude Code Setup
     • Gemini CLI Setup

3. Authorize AI

   • Run authorization command in AI
   • Approve in MCP Wallet (one-time approval)
   • Start using AI with your wallet!

4. Monitor Activity

   • Check transaction history regularly
   • All AI transactions are labeled
   • Disable API when not in use

OAuth 2.1 Flow

Authorization Process

sequenceDiagram
    participant User
    participant AI as AI Assistant
    participant Wallet as MCP Wallet
    participant OAuth as OAuth Server

    User->>AI: /mcp command
    AI->>Wallet: Authorization request
    Wallet->>User: Show authorization dialog
    User->>Wallet: Click "Approve"
    Wallet->>OAuth: Exchange code for token
    OAuth->>AI: Access token
    AI->>Wallet: Make API requests

Step by Step:

1. AI requests authorization

   • Generates PKCE challenge
   • Opens authorization URL in browser

2. You approve in MCP Wallet

   • Review requested permissions
   • Click "Approve" or "Deny"

3. Authorization code issued

   • Short-lived code (60 seconds)
   • Sent to OAuth server

4. Token exchange

   • OAuth server validates code
   • Issues access token (1 hour)
   • Issues refresh token (30 days)

5. AI uses tokens

   • Access token for API requests
   • Refresh token to get new access token
   • Re-authorization after 30 days

Token Management

Access Token:

• Lifetime: 1 hour
• Used for: All API requests
• Refresh: Automatically with refresh token

Refresh Token:

• Lifetime: 30 days
• Used for: Getting new access tokens
• Refresh: Requires re-authorization

Revocation:

• Disable API: Invalidates all tokens immediately
• Lock wallet: API access disabled until unlock

Model Context Protocol (MCP)

What is MCP?

MCP (Model Context Protocol) is a standard protocol for AI assistants to interact with external services.

Key Concepts:

• Tools: Functions AI can call (e.g., wallet_getBalance)
• Resources: Data AI can read (e.g., transaction history)
• Prompts: Pre-defined workflows

MCP Tools

MCP Wallet exposes these tools:

Tool	Description	Permission Required
wallet_getAddress	Get wallet address	wallet:read
wallet_getBalance	Get token balance	wallet:read
wallet_proposeTransaction	Send transaction	wallet:transaction
wallet_getTransactionStatus	Check tx status	wallet:read

See API Reference for full tool list.

Example Tool Calls

Get Balance:

{
  "tool": "wallet_getBalance",
  "parameters": {
    "token": "BNB"
  }
}

Response:

{
  "balance": "0.892",
  "token": "BNB",
  "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
}

Send Transaction:

{
  "tool": "wallet_proposeTransaction",
  "parameters": {
    "to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "amount": "100000000000000000",
    "token": "BNB"
  }
}

Response:

{
  "success": true,
  "txHash": "0x4952c33d1689cd57090d537052a1bc2efbc206cd65e36be048f04e4840cc75b7",
  "status": "pending"
}

Transaction Control

How You Stay in Control

After approving AI access during OAuth authorization:

• Monitor transactions: All AI transactions labeled as "AI-initiated"
• Transaction history: Review all AI activity in wallet
• Disable API: Instantly revoke AI access anytime
• Dedicated account: Use separate account with limited funds (recommended)

Best Practices for Control

1. Start with testnet - Test AI integration without real funds
2. Use dedicated account - Create separate account for AI access
3. Keep limited funds - Don't store large amounts in AI-accessible account
4. Monitor regularly - Check transaction history frequently
5. Disable when not in use - Turn off API access when not needed

Coming Soon: Spending Limits

Per-transaction and daily spending limits will be added in a future update to provide additional automated safeguards for AI transactions.

Common Use Cases

Portfolio Management

Check Portfolio:

User: What's my total portfolio value?
AI: You have:
- BNB: 0.892 (~$267)
- USDT: 50.00 (~$50)
Total: ~$317

Rebalance:

User: Send 0.2 BNB to my savings wallet
AI: Sending 0.2 BNB to 0x...
Transaction: 0x4952c3...

Regular Payments

Monthly Subscription:

User: Send 0.05 BNB to my VPN subscription
AI: Sending 0.05 BNB to 0x...
Done! Transaction confirmed.

Split Bills:

User: Split 0.3 BNB between Alice and Bob
AI: Sending:
- 0.15 BNB to Alice (0x...)
- 0.15 BNB to Bob (0x...)
Both transactions confirmed!

Development & Testing

Deploy Contract:

User: Deploy this contract to BSC testnet
AI: Checking balance... You have 1.5 testnet BNB
Deploying contract...
Contract deployed: 0xabc...

Test Transactions:

User: Send 0.01 testnet BNB to my test account
AI: Sending 0.01 BNB on BSC testnet...
Transaction: 0x123...

Monitoring AI Activity

Transaction History

All AI transactions are labeled:

1. Go to Transactions tab
2. Filter by "AI-initiated"
3. Review:
   • Amounts
   • Recipients
   • Timestamps
   • Status

Daily Spending

Track AI spending:

1. Settings → Accounts
2. View "Spending Today"
3. See:
   • Amount spent today
   • Daily limit
   • Remaining amount
   • Time until reset

Alerts

(Coming soon)

• Transaction notifications
• Limit approaching warnings
• Unusual activity alerts

Best Practices

For Beginners

1. ✅ Start on testnet - No real money risk
2. ✅ Use small amounts - Keep limited funds in AI account
3. ✅ Monitor closely - Check every transaction
4. ✅ Understand AI behavior - Learn patterns
5. ✅ Disable when unsure - Turn off API access if concerned

For Regular Users

1. ✅ Separate accounts - Dedicated AI account vs main account
2. ✅ Limited funds - Keep only needed amount in AI account
3. ✅ Review weekly - Check transaction history
4. ✅ Disable when unused - Turn off API access
5. ✅ Keep logs - Monitor for issues

For Advanced Users

1. ✅ Automated workflows - Regular payments, portfolio rebalancing
2. ✅ Multiple accounts - Different accounts per use case
3. ✅ Integration scripts - Custom automation
4. ✅ API monitoring - Track API usage patterns
5. ✅ Security audits - Regular security reviews

Troubleshooting

AI Can't Connect

Check:

• ✅ Wallet unlocked
• ✅ API enabled (Settings → Accounts)
• ✅ MCP server running (Settings → MCP Server)
• ✅ Correct OAuth configuration
• ✅ Firewall allows port 8580

Authorization Fails

Solutions:

1. Restart MCP Wallet
2. Check OAuth server is accessible
3. Clear AI cache and retry
4. Check MCP server logs

Transactions Rejected

Possible Causes:

• Insufficient balance
• Wrong network
• API disabled
• Invalid OAuth token

See Troubleshooting Guide for detailed solutions.

Security Checklist

Before enabling AI access:

□ Understand how OAuth 2.1 works
□ Understand one-time approval flow
□ Tested on testnet first
□ Created dedicated account for AI (recommended)
□ Know how to revoke access (disable API)
□ Monitoring plan in place
□ Comfortable with risk level

Next Steps

Choose your AI assistant:

• Claude Code Integration - Full setup guide
• Gemini CLI Integration - Full setup guide
• Codebuddy Integration - Full setup guide
• Other AI Clients - Generic HTTP integration guide
• SSE Transport (Trae) - For SSE-only clients
• Cursor Integration - Coming soon
• GitHub Copilot Integration - Coming soon

Or learn more:

• Security Guide - Understand security model
• Transaction Management - Learn about transactions
• API Reference - Technical details

---

Questions? See FAQ or join Telegram Community