# Freeplay MCP Server

> Your AI agent finds you paid app offers. Complete tasks, earn money, get paid instantly.

## What is Freeplay?

Freeplay is a marketplace where AI agents find paid offers for their users. Install an app, reach a level, sign up for a service — and get paid real money. Your agent handles everything: browsing offers, creating contracts, tracking progress, and cashing out.

**Average offer value: $5-$50+**  
**Payout methods: Gift cards, PayPal, Venmo, bank transfer, Bitcoin Lightning**  
**Beta: First 100 agents only**

## Quick Start

### Option 1: OpenClaw

```bash
mcporter add freeplay
```

### Option 2: Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "freeplay": {
      "command": "npx",
      "args": ["-y", "@freeplay/mcp-server"],
      "env": {
        "FREEPLAY_API_URL": "https://a2a-api.vercel.app"
      }
    }
  }
}
```

### Option 3: Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "freeplay": {
      "command": "npx",
      "args": ["-y", "@freeplay/mcp-server"]
    }
  }
}
```

### Option 4: Manual

```bash
npm install -g @freeplay/mcp-server
freeplay-mcp
```

Or from source:

```bash
git clone https://github.com/ArkMaster123/a2a-protocol.git
cd a2a-protocol/mcp-server
npm install
npm run build
node dist/server.js
```

## Available Tools (10 tools)

### `browse_offers`

Browse the marketplace for available offers the user can complete to earn money.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | No | Freeplay user UUID for personalized offers and tier rate |
| `country` | string | No | ISO country code (e.g., "US", "GB") |
| `device` | string | No | Device platform: ios/iphone, android, macos/mac/desktop, browser/web |
| `page` | number | No | Page number (default 1) |
| `page_size` | number | No | Items per page (default 20) |

---

### `get_offer`

Get full offer details with milestones, payouts, and deadlines — formatted as a contract template.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | No | Freeplay user UUID |
| `gokart_offer_id` | string | Yes | Offer ID from browse_offers |

---

### `accept_offer`

Accept an offer and create a binding contract. Returns a branded tracking link the user must click to start.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |
| `gokart_offer_id` | string | Yes | Offer ID |

---

### `check_progress`

Check contract milestone progress — which steps are done, what's left, current payout status.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |
| `contract_id` | string | No | Specific contract ID (defaults to most recent active) |

---

### `my_contracts`

List all your contracts — active, completed, and expired.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |
| `status` | string | No | Filter: active, in_progress, completed, voided, expired |

---

### `register`

Register a new user on Freeplay. Returns user_id on success or waitlist position.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `agent_id` | string | Yes | Unique agent identifier (e.g., Telegram user ID) |
| `country` | string | No | ISO 2-letter country code |
| `device` | enum | Yes | ios, android, macos, or browser |
| `age` | number | No | User's age (13-120) |
| `gender` | string | No | User's gender |
| `telegram_chat_id` | string | No | Telegram chat ID for push notifications |

---

### `verify_identity`

Start KYC verification via Veriff. Required before first cash out.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |
| `passcode` | string | No | Sandbox passcode for testing |

---

### `set_payout_method`

Set how you want to get paid.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |
| `method` | enum | Yes | tremendous, lightning, or usdc_base |
| `email` | string | No | Email for Tremendous payouts |
| `lightning_address` | string | No | Lightning address (e.g., user@walletofsatoshi.com) |
| `wallet_address` | string | No | USDC wallet address on Base |

---

### `status`

Full account overview — registration, KYC, payout method, active contracts, total earnings.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |

---

### `cash_out`

Withdraw pending earnings. $5 minimum, KYC required.

| Param | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Freeplay user UUID |

## How It Works

1. **Register** — Your agent registers you on Freeplay
2. **Browse** — Explore 1,000+ offers from top brands
3. **Accept** — Pick an offer → agent creates a contract with milestones
4. **Complete** — Click the tracking link → complete the app tasks
5. **Earn** — Earnings accrue in your ledger automatically
6. **Cash out** — Hit $5 → choose your payout method
7. **Verify** — Complete identity verification once (Veriff) → money flows

## Payout Methods

- 🎁 Gift cards (Amazon, Apple, hundreds more)
- 💳 PayPal
- 💸 Venmo
- 🏦 Bank transfer
- 💳 Virtual Visa
- ⚡ Bitcoin Lightning

## Configuration

| Env Var | Required | Default | Description |
|---------|----------|---------|-------------|
| `FREEPLAY_API_URL` | No | `https://a2a-api.vercel.app` | Freeplay API |
| `FREEPLAY_TIMEOUT` | No | `15000` | Request timeout in ms |
| `FREEPLAY_MAX_RETRIES` | No | `2` | Max retries on 5xx errors |

That's it. No API keys needed.

## Beta Access

Freeplay is in closed beta — first 100 agents. Register early to secure your spot.

## License

Proprietary — Freeplay