Other AI Clients

This guide provides configuration examples for AI clients that support the latest MCP specification (2024-11-25 or newer) with HTTP transport and OAuth 2.1.

Overview

If your AI client supports:

• ✅ HTTP Transport (not just SSE)
• ✅ OAuth 2.1 with PKCE
• ✅ MCP Specification 2024-11-25+

Then you can integrate directly with MCP Wallet without any adapter!

Prerequisites

Before configuring your AI client:

1. MCP Wallet installed - Installation Guide
2. Wallet created and unlocked - Getting Started
3. API access enabled - Settings → Accounts → Enable API toggle
4. MCP server running - Auto-starts on port 8580 when wallet unlocked

Standard Configuration

Configuration Format 1: Using serverUrl

Many modern MCP clients use the serverUrl property:

{
  "mcpServers": {
    "mcp-wallet": {
      "serverUrl": "http://127.0.0.1:8580/mcp"
    }
  }
}

Or with OAuth client ID:

{
  "mcpServers": {
    "mcp-wallet": {
      "serverUrl": "http://127.0.0.1:8580/mcp",
      "oauth": {
        "clientId": "your-ai-client-name"
      }
    }
  }
}

Configuration Format 2: Using url

Some MCP clients use the url property instead:

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://127.0.0.1:8580/mcp"
    }
  }
}

Or with OAuth client ID:

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://127.0.0.1:8580/mcp",
      "oauth": {
        "clientId": "your-ai-client-name"
      }
    }
  }
}

Configuration Format 3: Full OAuth Configuration

If your client requires explicit OAuth endpoints:

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://127.0.0.1:8580/mcp",
      "oauth": {
        "authorizationEndpoint": "http://localhost:8580/oauth/authorize",
        "tokenEndpoint": "https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token",
        "clientId": "your-ai-client-name",
        "scopes": ["wallet:read", "wallet:write"]
      }
    }
  }
}

Note: Most modern clients support OAuth metadata discovery, so you only need clientId. The client will auto-discover endpoints from http://localhost:8580/.well-known/oauth-authorization-server.

Key Configuration Points

Server URL

Standard port: 8580

Endpoint: /mcp

Full URL: http://127.0.0.1:8580/mcp or http://localhost:8580/mcp

Both 127.0.0.1 and localhost work, but 127.0.0.1 is more explicit.

OAuth Settings

Client ID:

• Can be any string (e.g., "cursor", "windsurf", "your-app-name")
• Will appear in MCP Wallet's authorized clients list
• Used to identify which AI client is making requests

Scopes:

• wallet:read - View addresses and balances
• wallet:write - Send transactions

Default scopes if not specified: ["wallet:read", "wallet:write"]

OAuth Endpoints:

Endpoint	URL
Authorization	http://localhost:8580/oauth/authorize
Token	https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token
Metadata	http://localhost:8580/.well-known/oauth-authorization-server

Modern MCP clients auto-discover these from the metadata endpoint.

Transport

Default: HTTP (no need to specify for modern clients)

Do NOT use SSE unless your client only supports the old MCP spec. See SSE Transport Guide for clients that require SSE.

Example Configurations

Cursor (Upcoming)

Expected config location: ~/.cursor/mcp_config.json or ~/.cursor/config.json

{
  "mcpServers": {
    "mcp-wallet": {
      "serverUrl": "http://127.0.0.1:8580/mcp",
      "oauth": {
        "clientId": "cursor"
      }
    }
  }
}

Windsurf

Config location: ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-wallet": {
      "serverUrl": "http://localhost:8580/mcp",
      "oauth": {
        "clientId": "windsurf"
      }
    }
  }
}

Generic MCP Client

For any MCP client supporting HTTP + OAuth 2.1:

{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://127.0.0.1:8580/mcp",
      "transport": "http",
      "oauth": {
        "clientId": "my-ai-assistant",
        "scopes": ["wallet:read", "wallet:write"]
      }
    }
  }
}

OAuth Authorization Flow

After configuring your AI client:

Step 1: First Request

When your AI client first tries to use MCP Wallet:

1. Client initiates OAuth authorization
2. Browser opens with authorization page
3. You may need to click "Auth" button on the page
4. MCP Wallet shows authorization dialog

Step 2: Authorization Dialog

In MCP Wallet dialog, review:

• Client ID: Name of your AI client
• Permissions: wallet:read wallet:write
• Account: Your wallet address

Click "Approve" or "Deny"

Step 3: Completion

1. Browser shows success page
2. You may need to click "Redirect" button
3. AI client receives access token
4. You can now use wallet features!

Step 4: Automatic Refresh

• Access tokens last 1 hour
• Refresh tokens last 30 days
• AI client auto-refreshes tokens when needed
• No repeated authorization required for 30 days

Available MCP Tools

Once authorized, your AI client can use these tools:

1. Get Wallet Address

Tool: wallet_get_address or mcp__mcp-wallet__wallet_get_address

Example:

User: What's my wallet address?
AI: Your wallet address is 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

2. Get Balance

Tool: wallet_get_balance or mcp__mcp-wallet__wallet_get_balance

Parameters:

• token (optional): Token symbol (e.g., "BNB", "USDT", "ETH")
• If omitted: Returns all token balances

Example:

User: How much BNB do I have?
AI: You have 0.892 BNB in your wallet.

3. Send Transaction

Tool: wallet_propose_transaction or mcp__mcp-wallet__wallet_propose_transaction

Parameters:

• to: Recipient address
• amount: Amount in Wei (smallest unit)
• token (optional): Token symbol (default: "USDT")

Example:

User: Send 0.1 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb
AI: Sending 0.1 BNB...
    Transaction sent successfully!
    Hash: 0x4952c33d...

4. Get Transaction Status

Tool: wallet_get_transaction_status or mcp__mcp-wallet__wallet_get_transaction_status

Parameters:

• tx_hash: Transaction hash

Example:

User: Check status of 0x4952c33d...
AI: Transaction is confirmed.
    Block: 42345678
    Status: Success

Security Best Practices

For Development

1. ✅ Start with testnet - Use BSC Testnet for initial testing
2. ✅ Small amounts - Test with small transaction amounts first
3. ✅ Understand behavior - Learn how your AI client uses the wallet
4. ✅ Monitor transactions - Check every transaction during development

For Production Use

1. ✅ Dedicated account - Create separate account for AI access
2. ✅ Limited funds - Keep only necessary amount in AI account
3. ✅ Regular monitoring - Review transaction history weekly
4. ✅ Revoke when unused - Disable API access when not needed
5. ✅ Strong password - Protect MCP Wallet with strong password

Access Control

What AI can do ✅:

• View wallet address
• Check token balances
• Send transactions (after OAuth approval)
• Check transaction status

What AI cannot do ❌:

• Access password or seed phrase
• Export private keys
• Modify security settings
• Delete accounts
• Change password
• Continue after API is disabled

Troubleshooting

AI Client Can't Connect

Problem: Connection failed or timeout errors

Solutions:

1. Verify MCP Wallet is running and unlocked
2. Check API access enabled: Settings → Accounts → Enable API
3. Check MCP server running: Settings → MCP Server → "Running"
4. Test manually:

   curl http://localhost:8580/mcp

5. Check firewall allows port 8580

OAuth Authorization Fails

Problem: Authorization doesn't complete

Solutions:

1. Make sure MCP Wallet is unlocked
2. Check browser opens authorization page
3. Click "Auth" button if shown
4. Approve in MCP Wallet dialog
5. Click "Redirect" button on success page
6. Check OAuth server is accessible:

   curl https://mcp-wallet-oauth.dev-taoist.workers.dev/health

Transactions Rejected

Problem: Transaction fails or is rejected

Check:

• ✅ Sufficient balance (including gas fees)
• ✅ Correct network (testnet vs mainnet)
• ✅ API still enabled
• ✅ Wallet unlocked
• ✅ Valid recipient address
• ✅ Amount in correct format (Wei for native tokens)

Token Expired

Problem: Invalid token or Unauthorized errors

Solutions:

1. Access tokens expire after 1 hour
2. AI client should auto-refresh - if not, manually re-authorize
3. Refresh tokens expire after 30 days - requires new authorization
4. Or revoke and re-authorize:
   • MCP Wallet → Settings → Authorized AI Clients → Revoke
   • Restart AI client session

Advanced Configuration

Multiple MCP Wallet Instances

If running multiple MCP Wallet instances on different ports:

{
  "mcpServers": {
    "mcp-wallet-main": {
      "serverUrl": "http://localhost:8580/mcp",
      "oauth": {
        "clientId": "my-client-main"
      }
    },
    "mcp-wallet-test": {
      "serverUrl": "http://localhost:9580/mcp",
      "oauth": {
        "clientId": "my-client-test"
      }
    }
  }
}

Custom OAuth Client ID

Use descriptive client IDs for better tracking:

{
  "mcpServers": {
    "mcp-wallet": {
      "serverUrl": "http://127.0.0.1:8580/mcp",
      "oauth": {
        "clientId": "mycompany-ai-dev"
      }
    }
  }
}

This will appear as "mycompany-ai-dev" in MCP Wallet's authorized clients list.

Monitoring Access

Track AI client access:

1. Transaction History

   • Open Transactions tab
   • Filter by "AI-initiated"
   • View all AI transactions

2. Authorized Clients

   • Settings → Authorized AI Clients
   • See active sessions
   • View last access time
   • Revoke specific client tokens

Network Support

Currently supported networks:

Network	Chain ID	Currency	Block Explorer
BSC Testnet	97	BNB	https://testnet.bscscan.com
BSC Mainnet	56	BNB	https://bscscan.com
Ethereum Mainnet	1	ETH	https://etherscan.io
Ethereum Sepolia	11155111	ETH	https://sepolia.etherscan.io
Polygon Mainnet	137	MATIC	https://polygonscan.com

Switch networks in: Settings → Network

FAQ

Do I need an adapter?

No! If your AI client supports HTTP transport and OAuth 2.1, connect directly to MCP Wallet on port 8580. No adapter needed.

What if my client only supports SSE?

See the SSE Transport Guide for clients using the old MCP specification.

Can I use custom ports?

Yes! Configure MCP Wallet to use a different port in Settings → MCP Server → Port. Then update your AI client config accordingly.

Is my seed phrase safe?

Yes! AI clients only get OAuth tokens for API access. They cannot access your seed phrase, private keys, or password. These are encrypted and never exposed via the API.

How do I revoke access?

Two ways:

1. Disable API for all clients: Settings → Accounts → Disable "Enable API" toggle
2. Revoke specific client: Settings → Authorized AI Clients → Find client → Revoke All

Need Help?

• 📢 Telegram Community - Get help from the community
• 🐛 GitHub Issues - Report bugs
• 📖 Full Documentation - Complete guides and references

Related Guides

• AI Integration Overview - Understand AI integration
• Claude Code Integration - Detailed setup example
• Gemini CLI Integration - Another setup example
• Codebuddy Integration - HTTP integration example
• Security Best Practices - Detailed security guide
• Transaction Management - Learn about transactions

---

Questions? See FAQ or join Telegram Community