# Connect to tip.md's MCP Service

## What is the MCP Service?

The Model Context Protocol (MCP) service allows AI assistants like Claude and Cursor to interact with tip.md's crypto tipping functionality directly. This enables your AI assistant to help users tip creators in cryptocurrency on Base and Solana networks without leaving their chat interface, using both advanced x402 payment protocol and traditional manual tipping methods.

### Available Tools

Our MCP server provides the following tools for AI assistants:

- **`tip_user_x402_on_base`** - Send USDC tips on Base network using x402 payment protocol with CDP automatic disbursement (built for Coinbase hackathon)
- **`tip_user_x402_on_solana`** - Send USDC tips on Solana network using x402 payment protocol with CDP automatic disbursement
- **`crypto_tipping`** - Provides transaction details for manual crypto tipping on Ethereum, Base, and Solana networks
- **`check_tipping_balance`** - Check your dedicated tipping wallet balance on Base and Solana networks, creates new wallets if none exist
- **`withdraw_tipping_funds`** - Withdraw USDC from your Base network tipping wallet to any Ethereum address
- **`export_tipping_wallet`** - Export your Base network tipping wallet private key for full control (security sensitive)
- **`get_user_wallet_types`** - Get configured wallet types for a specific tip.md user
- **`ping`** - Test MCP server connectivity and health check

### x402 Payment Protocol

The x402 payment protocol is an innovative HTTP-based payment system that enables automated cryptocurrency transactions. When an AI assistant calls our x402-enabled tools:

1. **Payment Request**: The tool makes an HTTP request that returns a `402 Payment Required` status
2. **Automatic Payment**: The x402 client automatically handles the blockchain transaction using your dedicated wallet
3. **Service Delivery**: Once payment is verified, the service (tip distribution) is completed automatically

**Key Benefits:**
- **Seamless Integration**: No manual wallet interactions needed
- **Dual Network Support**: Works on both Base and Solana networks
- **CDP Integration**: Leverages Coinbase's CDP (Coinbase Developer Platform) for secure, audited smart contract interactions
- **Automatic Fee Distribution**: Built-in 4% platform fee handling with 96% going to creators

### Dedicated Tipping Wallets

The MCP server creates and manages dedicated custodial wallets for users:

- **Base Network Wallet**: For USDC transactions on Base (lower fees, faster confirmation)
- **Solana Network Wallet**: For USDC transactions on Solana (ultra-low fees, near-instant confirmation)
- **Encrypted Storage**: Private keys are encrypted and stored securely in our database
- **Easy Management**: Check balances, withdraw funds, or export private keys through MCP tools

### Hackathon Innovation 🏆

*This MCP server was built for a Coinbase hackathon leveraging CDP tools, showcasing the innovative [TipMD project](https://devfolio.co/projects/tipmd-d033) that transforms any AI agent into a payment-enabled tipping agent using x402 payment collection with CDP automatic disbursement on Base and Solana networks.*

## Cursor Setup

1. **Open Cursor's MCP Configuration:**
   - Edit or create the file at `~/.cursor/mcp.json`

2. **Add our tip.md service:**
   ```json
   {
     "mcpServers": {
       "tip.md": {
         "command": "npx", 
         "args": ["-y", "mcp-remote", "https://mcp.tip.md/mcp"]
       }
     }
   }
   ```

3. **Enable the tip.md service**
   - Open Cursor's MCP settings panel and enable the tip.md service.

## Sage App Setup

[Sage](https://sageapp.ai) is a native AI client that supports MCP and can be easily connected to tip.md. Here's how to set it up:

1. **Go to Tools**
   - Open the Sage app and navigate to the Tools section in the settings.

2. **MCP Servers under MCP Configuration**
   - Find and select the MCP Servers section under MCP configuration.

3. **Click on "Add Server"**
   - This will open the server configuration dialog.

4. **Add the configuration details**
   - Enter the following information:
     - Connection Type: **Streamable HTTP**
     - Server Name: **tip.md**
     - Endpoint URL: **https://mcp.tip.md/mcp**

5. **Click "Add" to save the configuration**
   - The tip.md server should now appear in your list of available MCP servers.

6. **Test in the chat**
   - Return to chat and ask Sage about tip.md functionality, such as "What tools are available for tip.md?" or "How can I check a user's wallet types?"

## Claude Desktop Setup

Since Claude Desktop only supports stdio transport for MCP servers, you need to use [Supergateway](https://github.com/supercorp-ai/supergateway) to bridge our HTTP-stream transport to stdio.

### Prerequisites
- **Node.js**: Installed on your system (download from [nodejs.org](https://nodejs.org))
- **Claude Desktop**: Latest version installed
- **[Supergateway](https://github.com/supercorp-ai/supergateway)**: Install globally via npm:
  ```
  npm install -g supergateway
  ```
- **Docker (Optional)**: If you prefer running Supergateway in a container

### Steps to Add the MCP Server to Claude Desktop

1. **Run [Supergateway](https://github.com/supercorp-ai/supergateway) to Bridge HTTP-Stream to Stdio**
   - [Supergateway](https://github.com/supercorp-ai/supergateway) supports HTTP-stream transport as an input, converting it to stdio for Claude Desktop:
   ```
   npx -y supergateway --httpStream "https://mcp.tip.md/mcp" --outputTransport stdio
   ```

2. **Configure Claude Desktop**
   - Locate or create the Claude Desktop configuration file:
     - **Windows:** `C:\Users\YourUsername\AppData\Roaming\Claude\claude_desktop_config.json`
     - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   
   - Add the [Supergateway](https://github.com/supercorp-ai/supergateway) command to the configuration:
   ```json
   {
     "mcpServers": {
       "tip-md-mcp": {
         "command": "npx",
         "args": [
           "-y",
           "supergateway",
           "--httpStream",
           "https://mcp.tip.md/mcp",
           "--outputTransport",
           "stdio"
         ]
       }
     }
   }
   ```
   - Save the file and restart Claude Desktop.

3. **Verify the Setup**
   - Open Claude Desktop and look for the hammer icon in the bottom right corner of the input box.
   - Test the server by asking "How can I tip user tipdotmd?".
   - If the server doesn't appear, check logs:
     - **macOS**: `tail -n 20 -f ~/Library/Logs/Claude/mcp*.log`
     - **Windows**: `type "%APPDATA%\Claude\logs\mcp*.log"`

### Notes and Troubleshooting
- **HTTP-Stream Transport**:
  - HTTP-stream is a newer transport replacing SSE in the MCP protocol. Ensure you're using the latest Supergateway:
    ```bash
    npm update -g supergateway
    ```
- **Debugging**:
  - If the hammer icon doesn't appear, verify Supergateway is running without errors (check terminal output).
  - Test the server independently using a tool like Postman or a custom MCP client.
- **Alternative Clients**:
  - Consider clients like Cursor, which natively support HTTP-stream transport, avoiding the need for Supergateway.

## Other MCP Clients

For clients other than Cursor or Claude Desktop:

1. Find your client's method for configuring MCP servers
2. Configure it to an "http-stream" transport and connect to `https://mcp.tip.md/mcp`
3. If your client supports command-based MCP connections, use:
   ```
   npx -y --package=@modelcontextprotocol/remote mcp-remote https://mcp.tip.md/mcp
   ```

## Troubleshooting

- **Connection issues?**
  - Verify you can reach our service with: `curl -I https://mcp.tip.md/mcp`

- **Tool not showing?**
  - Make sure to fully restart your client after configuration.

- **Any other issues?**
  - Reach out to us at [support@tip.md](mailto:support@tip.md)

*Our MCP service was built using the excellent [mcp-framework](https://mcp-framework.com/).*