Tip Md X402 MCP Server

1# [tip.md](https://tip.md) x402 + CDP MCP Server
2 
3> **🏆 Hackathon Entry**: Transform any AI agent into a payment-enabled tipping agent using x402 payment collection with CDP automatic disbursement.
4 
5## 🌟 About tip.md
6 
7**tip.md** is a platform that allows developers to receive cryptocurrency tips directly to their wallets via a simple button embeddable in GitHub READMEs, websites, or any markdown content. It supports:
8 
9- **Multiple Blockchains**: Ethereum, Base,Solana, and Bitcoin Lightning Network
10- **Direct-to-Wallet Payments**: Tips go straight to your wallet, no custody
11- **Simple Integration**: One button, works everywhere markdown is supported
12- **4% Platform Fee**: Transparent pricing, we only make money if you do
13- **Client-Side Security**: All transactions processed securely in the browser
14 
15This MCP server extends tip.md's functionality by enabling **any AI agent** to facilitate crypto tipping through the innovative x402 + CDP integration.
16 
17## 🚀 Quick Demo (No Setup Required)
18 
19**For Judges & Evaluators**: Experience the x402 + CDP tipping flow instantly:
20 
21```bash
22git clone https://github.com/xR0am/tip-md-x402-mcp-server.git
23cd tip-md-x402-mcp-server
24npm install
25NODE_ENV=demo npm start
26```
27 
28**⚠️ Important**: The server running alone shows logs, but to see the **demo payment functionality**, you need to connect it to an MCP client (see [Testing with MCP Clients](#testing-with-mcp-clients) below).
29 
30## 🎯 What This Does
31 
32**Core Innovation**: ANY AI agent + this MCP = instant payment-enabled agent
33 
34- **x402 Payment Collection**: Users pay from dedicated wallets using the x402 payment protocol (Money IN)
35- **CDP Automatic Disbursement**: Backend automatically splits payments (96% recipient, 4% platform) via Coinbase Wallet API (Money OUT)
36- **MCP Tool Integration**: Works with Claude, ChatGPT, Cursor, or any MCP-compatible agent
37- **True Composability**: Transform existing AI workflows into payment-enabled experiences
38 
39### 🔄 The Complete Flow
40 
411. **User: "Check balance"** → Agent: *"47.50 USDC available for tipping"*
422. **User asks AI agent**: "Tip @username 5 USDC"
433. **x402 Payment Collection**: Agent generates payment request, user pays from dedicated wallet
444. **CDP Automatic Disbursement**: Backend splits payment and sends to recipient + platform
455. **AI Confirms**: "✅ Sent 5 USDC to @username"
46 
47## Architecture: True x402 → CDP Flow
48 
49### User Payment Flow
50```
51User → Dedicated Tipping Wallet → x402 Payment Collection → CDP Agent Wallet → CDP Disburses to Recipient (96%) + Platform (4%)
52```
53 
54## 📋 Available MCP Tools
55 
56This MCP server exposes **7 tools** that any AI agent can use:
57 
58### **💰 x402 + CDP Payment Tools (Hackathon Innovation)**
59- **`mcp_tip_md_tip_on_base`**: Send USDC tips on Base using x402 payment protocol with CDP automatic disbursement
60- **`mcp_tip_md_tip_on_solana`**: Send USDC tips on Solana using x402 payment protocol
61- **`mcp_tip_md_check_tipping_balance`**: Check/create your dedicated tipping wallet balance and info
62 
63### **🔧 Wallet Management Tools**  
64- **`mcp_tip_md_export_tipping_wallet`**: Export your tipping wallet private key (security sensitive)
65- **`mcp_tip_md_withdraw_tipping_funds`**: Withdraw USDC from your tipping wallet to any address
66 
67### **🔍 User & Network Tools**
68- **`mcp_tip_md_get_user_wallet_types`**: Check recipient's supported cryptocurrencies and wallet types
69- **`mcp_tip_md_crypto_tipping`**: Manual crypto tipping information for agents with wallet to instruct (Ethereum, Base, Solana - no x402/CDP flow)
70 
71### **🏥 System Tools**
72- **`mcp_tip_md_ping`**: Health check endpoint
73 
74## 🧪 Testing with MCP Clients
75 
76To see the **actual demo payment functionality**, you need to connect the MCP server to a compatible client:
77 
78### Cursor IDE Setup
79 
801. **Edit your MCP configuration** (`~/.cursor/mcp.json`):
81```json
82{
83  "mcpServers": {
84    "tip-md-demo": {
85      "command": "node",
86      "args": ["dist/mcp-server/src/index.js"],
87      "cwd": "/path/to/tip-md-x402-mcp-server",
88      "env": {
89        "NODE_ENV": "demo"
90      }
91    }
92  }
93}
94```
95 
962. **Restart Cursor** and look for the 🔨 tools icon
97 
983. **Test the demo**:
99   - Type: "Tip user johndoe 5 USDC using base blockchain"
100   - Watch the x402 + CDP simulation in action!
101 
102### Claude Desktop Setup
103 
1041. **Install Supergateway** (bridges our HTTP transport to stdio):
105```bash
106npm install -g supergateway
107```
108 
1092. **Configure Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
110```json
111{
112  "mcpServers": {
113    "tip-md-demo": {
114      "command": "npx",
115      "args": [
116        "-y",
117        "supergateway",
118        "--httpStream",
119        "http://localhost:3000/mcp",
120        "--outputTransport",
121        "stdio"
122      ]
123    }
124  }
125}
126```
127 
1283. **Start the MCP server** in demo mode:
129```bash
130NODE_ENV=demo npm start
131```
132 
1334. **Restart Claude Desktop** and test with: "Show me available tip.md tools"
134 
135### Other MCP Clients
136 
137For clients supporting HTTP-stream transport:
138- **Endpoint**: `http://localhost:3000/mcp` (when running locally)
139- **Transport**: HTTP-stream
140- **Environment**: Set `NODE_ENV=demo` for simulation mode
141 
142## 🛠️ Production Integration (Requires Setup)
143 
144For full integration with the tip.md platform:
145 
146### Environment Variables
147 
148Create a `.env` file:
149 
150```bash
151# Database Connection (Required for production)
152MONGODB_URI=mongodb+srv://username:password@cluster.mongodb.net/database
153 
154# Coinbase Developer Platform (Required for CDP disbursement)
155CDP_API_KEY_ID=your_cdp_api_key_id
156CDP_API_KEY_SECRET=your_cdp_api_key_secret
157 
158# x402 Configuration (Required for payment collection)
159X402_WALLET_PRIVATE_KEY=your_x402_wallet_private_key
160 
161# Optional Configuration
162PORT=3000
163NODE_ENV=production
164LOG_LEVEL=info
165```
166 
167### Production Deployment
168 
169```bash
170npm install
171npm run build
172npm start
173```
174 
175## 🏗️ Technical Architecture
176 
177### x402 Payment Collection
178- **Dedicated Wallets**: Each user gets a unique payment wallet
179- **Protocol Compliance**: Full x402 specification implementation
180  
181### CDP Automatic Disbursement  
182- **Smart Splitting**: 96% to recipient, 4% to platform
183- **Instant Settlement**: Automated via Coinbase Developer Platform
184 
185### MCP Integration
186- **Universal Compatibility**: Works with any MCP-compatible AI agent
187- **Structured Responses**: Rich JSON responses for seamless integration
188- **Error Handling**: Graceful fallbacks and detailed error messages
189 
190## 🎖️ Hackathon Submission Details
191 
192**Challenge**: Coinbase x402 + CDP Integration
193**Innovation**: Universal AI agent payment enablement
194**Demo Mode**: `NODE_ENV=demo npm start`
195**Repository**: https://github.com/xR0am/tip-md-x402-mcp-server
196 
197### Key Differentiators
198 
1991. **Universal Agent Integration**: Any MCP client becomes payment-enabled
2002. **Complete Payment Flow**: x402 collection + CDP disbursement in one solution
2013. **Zero-Setup Demo**: Judges can evaluate immediately
2024. **Production-Ready**: Already integrated with tip.md platform
203 
204## 📚 Learn More
205 
206- **tip.md Platform**: https://tip.md
207- **MCP Protocol**: https://modelcontextprotocol.io
208- **x402 Specification**: https://docs.coinbase.com/x402
209- **Coinbase CDP**: https://docs.cdp.coinbase.com
210 
211## 🤝 Support
212 
213For questions about this hackathon entry:
214- **Issues**: Open a GitHub issue
215- **Email**: support@tip.md
216- **Demo Problems**: Ensure you're testing through an MCP client, not just the server logs
217 
218---
219 
220**Built for the Coinbase x402 + CDP Hackathon** 🏆
221