MCP Wallet

Appearance

SSE Transport Support ​

Some AI assistants (like Trae) only support Server-Sent Events (SSE) transport for the Model Context Protocol (MCP), using the old MCP specification (2024-11-05). Since MCP Wallet natively uses HTTP transport with the latest MCP specification, we provide an SSE Adapter v2.0 - a lightweight proxy with OAuth coordination that enables full compatibility with old-spec MCP clients.

What is SSE Transport? ​

Server-Sent Events (SSE) is a server-to-client streaming protocol where the server can push data to the client over a single HTTP connection. Some MCP clients require this transport type instead of standard HTTP request/response.

Do You Need the SSE Adapter? ​

You DON'T need it if you're using:

  • ✅ Claude Code (supports HTTP transport)
  • ✅ Gemini CLI (supports HTTP transport)
  • ✅ Codebuddy (supports HTTP transport)

You NEED it if you're using:

  • ⚠️ Trae (SSE only - old MCP spec 2024-11-05)
  • ⚠️ Other SSE-only MCP clients (old MCP spec 2024-11-05)

How It Works ​

The SSE Adapter v2.0 acts as an OAuth coordinator and protocol translator:

┌──────────────┐         SSE          ┌──────────────┐        HTTP         ┌──────────────┐
│ AI Assistant │ ◄─────────────────► │ SSE Adapter  │ ◄─────────────────► │  MCP Wallet  │
│ (Trae/       │   Server-Sent Events │   v2.0       │   HTTP JSON-RPC     │   (HTTP)     │
│  Codebuddy)  │                      │              │                     │              │
└──────────────┘                      └──────────────┘                     └──────────────┘
                                             │
                                             │ Token Exchange
                                             ▼
                                      ┌──────────────┐
                                      │OAuth Server  │
                                      │(Cloudflare)  │
                                      └──────────────┘

What the adapter does:

  1. Receives SSE requests from AI clients
  2. Manages OAuth flow - coordinates authorization and stores tokens
  3. Client fingerprinting - shares sessions across multiple SSE connections
  4. Converts SSE to HTTP and forwards to MCP Wallet
  5. Auto-injects tokens - transparently adds authorization
  6. Converts HTTP responses back to SSE format

v2.0 Key Features:

  • ✅ One-time authorization - No repeated OAuth popups
  • ✅ Auto-browser opening - Automatically opens authorization dialog
  • ✅ Session management - Handles tokens for old-spec clients
  • ✅ Client fingerprinting - Reuses sessions across connections

Installation ​

Prerequisites ​

  • Node.js v18.0.0 or higher
  • MCP Wallet installed and running

Download SSE Adapter ​

Option 1: From GitHub

bash
# Clone the repository
git clone https://github.com/teamtaoist/mcp-wallet-sse-adapter.git
cd mcp-wallet-sse-adapter

# Install dependencies
npm install

Option 2: NPM Package (Coming Soon)

bash
npm install -g mcp-wallet-sse-adapter

Quick Start ​

Step 1: Start MCP Wallet ​

  1. Launch MCP Wallet application
  2. Unlock your wallet with your password
  3. Verify MCP server is running on port 8580

Step 2: Start SSE Adapter ​

bash
# If installed from source
npm start

# If installed globally (when available)
mcp-wallet-sse-adapter

You should see:

==============================================
MCP Wallet SSE Adapter v2.0
==============================================
Adapter URL:     http://localhost:8581
MCP Endpoint:    http://localhost:8581/mcp
MCP Wallet URL:  http://localhost:8580
OAuth Server:    https://mcp-wallet-oauth.dev-taoist.workers.dev
Transport:       Server-Sent Events (SSE)
Mode:            Dual (Passthrough + OAuth Coordinator)
==============================================

✓ SSE Adapter is running
✓ Passthrough mode: For clients with Authorization header
✓ OAuth Coordinator mode: For old-spec clients (Trae, Codebuddy)

Step 3: Configure Your AI Assistant ​

Point your AI assistant to the SSE Adapter (port 8581) instead of MCP Wallet directly.

Trae Configuration ​

File: ~/.trae/config.json

json
{
  "mcpServers": {
    "mcp-wallet": {
      "url": "http://localhost:8581/mcp",
      "transport": "sse",
      "oauth": {
        "authorizationEndpoint": "http://localhost:8581/oauth/authorize",
        "tokenEndpoint": "https://mcp-wallet-oauth.dev-taoist.workers.dev/oauth/token",
        "clientId": "trae",
        "scopes": ["wallet:read", "wallet:write"]
      }
    }
  }
}

Key points:

  • URL points to adapter (:8581), not MCP Wallet (:8580)
  • transport: "sse" is required
  • OAuth authorization endpoint uses adapter URL
  • Token endpoint stays the same (Cloudflare Workers)

Other SSE-Only Clients ​

File: Configuration file location varies by client

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

Step 4: Authorize AI Assistant ​

When your AI assistant first tries to use MCP Wallet:

  1. Adapter automatically opens your browser with authorization dialog
  2. MCP Wallet shows authorization dialog
  3. Review the permissions:
    • Client name (e.g., "trae" or "codebuddy")
    • Permissions requested
    • Your account address
  4. Click "Approve"
  5. Browser shows success page (you can close it)
  6. Done! AI assistant can now access your wallet via SSE

Note: With v2.0, you only need to authorize once per client. The adapter remembers your authorization for 30 minutes, so all subsequent requests work automatically without repeated popups.

Step 5: Test the Connection ​

Try these commands in your AI assistant:

Check wallet address:

What's my wallet address?

Check balance:

How much BNB do I have?

Send test transaction (testnet recommended):

Send 0.001 BNB to 0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Configuration ​

Environment Variables ​

You can customize the adapter with environment variables:

bash
# Port for SSE adapter (default: 8581)
PORT=8581

# MCP Wallet URL (default: http://localhost:8580)
MCP_WALLET_URL=http://localhost:8580

Custom Port ​

If port 8581 is already in use:

bash
PORT=8582 npm start

Then update your AI client config to use port 8582.

Custom MCP Wallet URL ​

If MCP Wallet is running on a different port:

bash
MCP_WALLET_URL=http://localhost:9580 npm start

How SSE Adapter Works ​

Message Flow ​

  1. AI Client → Sends JSON-RPC request via SSE
  2. Adapter → Converts SSE to HTTP POST
  3. MCP Wallet → Processes request
  4. Adapter → Converts HTTP response to SSE events
  5. AI Client → Receives response via SSE stream

SSE Events ​

The adapter sends these SSE events:

endpoint event - Connection established

event: endpoint
data: {"type":"endpoint","message":"Connected to MCP Wallet SSE Adapter"}

message event - MCP response data

event: message
data: {"jsonrpc":"2.0","result":{"balance":"0.892"},"id":1}

done event - Request completed

event: done
data: {"status":"completed","timestamp":"2025-01-10T..."}

error event - Error occurred

event: error
data: {"error":"wallet_locked","error_description":"Wallet is locked"}

OAuth Flow ​

v2.0 OAuth Coordinator Mode (for old-spec clients like Trae):

  1. Client connects via SSE without authorization
  2. Adapter detects unauthorized request
  3. Adapter auto-opens browser with authorization URL
  4. User approves in MCP Wallet UI
  5. MCP Wallet redirects to adapter's /oauth/callback
  6. Adapter exchanges code for token (with OAuth server)
  7. Adapter stores token in session (linked to client via fingerprinting)
  8. Browser shows success page
  9. All subsequent requests automatically use stored token

Benefits of v2.0:

  • ✅ One authorization per client - No repeated OAuth flows
  • ✅ Automatic token management - Adapter handles everything
  • ✅ Session reuse - Multiple SSE connections share one session
  • ✅ Auto-refresh - Tokens refreshed automatically before expiry

For detailed OAuth flow documentation, see the SSE Adapter Repository.

Troubleshooting ​

Adapter Won't Start ​

Error: EADDRINUSE: address already in use :::8581

Solution: Port 8581 is already in use. Change port:

bash
PORT=8582 npm start

Cannot Connect to MCP Wallet ​

Error: Connection errors or fetch failed

Solutions:

  1. Verify MCP Wallet is running
  2. Check MCP Wallet is on port 8580 (default)
  3. Try specifying URL explicitly:
    bash
    MCP_WALLET_URL=http://localhost:8580 npm start

AI Client Can't Connect to Adapter ​

Problem: AI client shows connection error

Solutions:

  1. Verify adapter is running (npm start)
  2. Test health endpoint: curl http://localhost:8581/health
  3. Check AI client config:
    • URL: http://localhost:8581/mcp
    • Transport: "sse"
  4. Restart both adapter and AI client

OAuth Authorization Fails ​

Problem: Authorization dialog doesn't appear

Solutions:

  1. Make sure MCP Wallet is unlocked
  2. Check API access is enabled: Settings → Accounts → Enable API
  3. Verify MCP server is running in MCP Wallet

Transactions Fail ​

Problem: Transactions rejected or failed

Solutions:

  1. Insufficient funds - Check you have enough balance + gas
  2. Wrong network - Verify you're on correct network (testnet vs mainnet)
  3. API disabled - Check API access still enabled
  4. Wallet locked - Unlock wallet in MCP Wallet app

Security ​

The SSE Adapter is designed with security in mind:

Security Features ​

  • ✅ Local Only - Binds to 127.0.0.1 (localhost) only
  • ✅ No Storage - Completely stateless, no data stored
  • ✅ Token Passthrough - OAuth tokens passed transparently, never stored
  • ✅ No Logging of Secrets - Tokens and sensitive data not logged
  • ✅ Open Source - Code is auditable and transparent

What Adapter CANNOT Do ​

  • ❌ Store your passwords or seed phrases
  • ❌ Access your private keys
  • ❌ Modify security settings
  • ❌ See your OAuth tokens (just passes through)
  • ❌ Work without MCP Wallet running

Best Practices ​

  1. Only run locally - Never expose adapter to internet
  2. Keep it updated - Update to latest version regularly
  3. Monitor logs - Check adapter logs for unusual activity
  4. Close when not needed - Stop adapter when not using AI assistant

Performance ​

The adapter adds minimal overhead:

  • Latency: < 10ms per request
  • Memory: ~30MB RAM usage
  • CPU: Negligible (stateless proxy)
  • Concurrent Requests: Supports multiple simultaneous AI clients

Limitations ​

  • Local Only: Designed for localhost usage only
  • No SSL: HTTP only (MCP Wallet also uses HTTP locally)
  • Single MCP Wallet: Proxies to one MCP Wallet instance at a time

Advanced Usage ​

Running Multiple Instances ​

You can run multiple adapter instances for different MCP Wallet instances:

Adapter 1 (Port 8581 → MCP Wallet Port 8580):

bash
PORT=8581 MCP_WALLET_URL=http://localhost:8580 npm start

Adapter 2 (Port 8582 → MCP Wallet Port 9580):

bash
PORT=8582 MCP_WALLET_URL=http://localhost:9580 npm start

Health Monitoring ​

Check if adapter is healthy:

bash
curl http://localhost:8581/health

Response:

json
{
  "status": "healthy",
  "adapter": "mcp-wallet-sse-adapter",
  "version": "2.0.0",
  "mcpWalletUrl": "http://localhost:8580",
  "oauthServerUrl": "https://mcp-wallet-oauth.dev-taoist.workers.dev",
  "transport": "SSE",
  "mode": "dual (passthrough + oauth-coordinator)",
  "sessions": {
    "total": 3,
    "active": 2,
    "authorized": 1,
    "expired": 1
  },
  "oauth": {
    "pendingFlows": 0
  }
}

Logs ​

The adapter logs important events to help with debugging:

bash
[SSE] Received request: {"method":"tools/list","hasAuth":true}
[SSE] MCP Wallet response: {"hasResult":true,"hasError":false}
[OAuth] Authorization request received: {"clientId":"trae"}

Next Steps ​

Now that you have SSE transport working:

Need Help? ​

MCP Wallet - Secure crypto wallet with AI integration

Copyright © 2025 MCP Wallet