tip-md-x402

tip.md-x402 MCP server extends the tip.md tipping platform to enable any AI agent to coordinate crypto tips using the x402 payment collection and CDP automatic disbursement flow. The server exposes seven tools that an agent can call to manage tips, wallets, user data, and health checks, allowing a seamless demonstration of tips flowing from a user’s dedicated tipping wallet through x402 into recipient wallets with automatic 4% platform disbursement. The demo mode simulates the real flow, so you can test the MCP integration with compatible clients (e.g., Cursor, Claude Desktop, or other MCP clients) and observe the x402 + CDP disbursement in action. The tools cover tip creation on Base and Solana, wallet export/withdrawal, user wallet capability discovery, manual tipping instructions, and a health ping.

Prerequisites:

• Node.js and npm installed on your machine
• Git to clone repositories

Step-by-step installation:

# 1) Clone the MCP server repository
git clone https://github.com/xR0am/tip-md-x402-mcp-server.git
cd tip-md-x402-mcp-server

# 2) Install dependencies
npm install

# 3) Build (if applicable) or prepare for run
# If a build step exists in package.json, run it; otherwise skip
npm run build || true

# 4) Run in demo mode (example)
NODE_ENV=demo npm start

Environment and configuration:

• For a production run, set NODE_ENV=production and ensure required env vars are provided (see README under Production Environment Variables).
• If running via the MCP client integration, ensure the client configuration points to the correct MCP server and transport (e.g., HTTP-stream for some clients).

Tips and common issues:

• Ensure you connect to a compatible MCP client to see the actual demo tipping flow; the server logs may run without the demo until a client connects.
• For production, provide all required environment variables (MONGODB_URI, CDP_API_KEY_ID/SECRET, X402_WALLET_PRIVATE_KEY) as described in the README.
• The seven tools include: mcp_tip_md_tip_on_base, mcp_tip_md_tip_on_solana, mcp_tip_md_check_tipping_balance, mcp_tip_md_export_tipping_wallet, mcp_tip_md_withdraw_tipping_funds, mcp_tip_md_get_user_wallet_types, mcp_tip_md_crypto_tipping, and mcp_tip_md_ping. Use these to simulate tipping, review wallet status, and perform administrative actions.
• When testing with Claude Desktop or Cursor IDE, ensure NODE_ENV=demo is set to enable the demo flow and simulated responses.
• If you encounter transport issues, verify that the MCP client is configured to the correct endpoint (http://localhost:3000/mcp) and transport (HTTP-stream for demo integrations).
• Review the environment variable section in the README to tailor your deployment (PORT, NODE_ENV, LOG_LEVEL, etc.).