# @purpleflea/identity-mcp

**MCP server for Purple Flea Identity — disposable email & phone numbers for AI agents.**

Purple Flea is blue chip infrastructure for autonomous AI agents. Create disposable email addresses and rent real phone numbers on demand. OTP and verification codes are auto-extracted from incoming messages. Identities self-destruct after TTL expires.

Built on the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), this package gives any MCP-compatible AI agent (Claude, GPT, Gemini, open-source) instant access to identity infrastructure.

## Why Purple Flea?

- **First mover** in disposable identity infrastructure for AI agents
- **Auto-extracts OTP codes** from email and SMS — no regex needed
- **Self-destructing identities** — set TTL, forget about cleanup
- **Real phone numbers** in 6 countries (US, CA, GB, DE, FR, NL)
- **One-call verification** — `wait_for_otp` handles the entire flow
- **10% referral commission** — agents earn passive income by referring other agents
- **Crypto funding** — deposit on Base, Ethereum, Solana, Bitcoin, Monero, and more
- **Free tier** — 5 emails/day, 2 SMS/day, 3 verifications/day, no payment required

## Quick Start

### Install via npx (no install needed)

```bash
npx @purpleflea/identity-mcp
```

### Or install globally

```bash
npm install -g @purpleflea/identity-mcp
```

### Claude Desktop Configuration

Add to your Claude Desktop `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "purpleflea-identity": {
      "command": "npx",
      "args": ["-y", "@purpleflea/identity-mcp"],
      "env": {
        "PURPLE_FLEA_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Cursor / VS Code Configuration

Add to your MCP settings:

```json
{
  "purpleflea-identity": {
    "command": "npx",
    "args": ["-y", "@purpleflea/identity-mcp"],
    "env": {
      "PURPLE_FLEA_API_KEY": "your-api-key-here"
    }
  }
}
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PURPLE_FLEA_API_KEY` | Your API key (get one with the `register` tool) | — |
| `PURPLE_FLEA_BASE_URL` | API base URL | `http://localhost:3001` |

## Tools

### `register`

Register a new AI agent account. Returns API key, agent ID, and referral code. **Call this first** if you don't have an API key.

| Parameter | Type | Description |
|-----------|------|-------------|
| `referral_code` | string (optional) | Referral code from another agent for 10% commission program |

### `create_identity`

Create a disposable email address or rent a real phone number.

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | `"email"` \| `"phone"` | Type of identity to create |
| `ttl` | number (optional) | Time-to-live in seconds |
| `country` | string (optional) | Country for phone: US, CA, GB, DE, FR, NL |
| `webhook` | string (optional) | URL to POST incoming messages to |
| `domain` | string (optional) | Email domain (default: tempbox.ai) |

**Pricing:**
- Email: $0.05 (or free, 5/day)
- Phone: $0.30 (10min) / $0.50 (1hr) / $1.00 (24hr) / $5.00 (30 days)

### `get_inbox`

Check the email inbox. Returns all messages with auto-extracted verification codes.

| Parameter | Type | Description |
|-----------|------|-------------|
| `address` | string | The disposable email address |
| `codes_only` | boolean (optional) | Return only extracted OTP codes |
| `latest_only` | boolean (optional) | Return only the most recent email |

### `get_sms`

Check SMS inbox of a rented number. Returns messages with auto-extracted codes.

| Parameter | Type | Description |
|-----------|------|-------------|
| `number` | string | The rented phone number |
| `codes_only` | boolean (optional) | Return only extracted OTP codes |
| `latest_only` | boolean (optional) | Return only the most recent SMS |

### `wait_for_otp`

**All-in-one verification.** Creates a disposable email or rents a phone, waits for a verification code, and returns it. One tool call handles the entire flow.

| Parameter | Type | Description |
|-----------|------|-------------|
| `method` | `"email"` \| `"sms"` | Verification method |
| `country` | string (optional) | Country for SMS (default: US) |
| `timeout` | number (optional) | Max seconds to wait (default: 120, max: 300) |
| `wait` | boolean (optional) | Long-poll until code arrives (default: true) |
| `webhook` | string (optional) | URL to POST code to when received |

**Pricing:** Email $0.10, SMS $0.50

### `poll_verification`

Poll for the result of a pending `wait_for_otp` request (when called with `wait=false`).

| Parameter | Type | Description |
|-----------|------|-------------|
| `request_id` | string | The requestId from wait_for_otp |

### `extend_ttl`

Update the webhook URL for a disposable email address.

| Parameter | Type | Description |
|-----------|------|-------------|
| `address` | string | The disposable email address |
| `webhook` | string | New webhook URL |

### `destroy_identity`

Immediately destroy a disposable email or release a rented phone number. All messages are permanently deleted.

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | `"email"` \| `"phone"` | Type of identity |
| `identifier` | string | Email address or phone number |

### `list_identities`

List all active (non-expired) identities.

| Parameter | Type | Description |
|-----------|------|-------------|
| `type` | `"email"` \| `"phone"` \| `"all"` (optional) | Filter by type (default: all) |

### `referral_stats`

View your referral program stats: referral code, referred agents, and total earnings.

No parameters required.

### `check_balance`

Check account balance, tier, deposits, spending, and referral earnings.

No parameters required.

### `check_usage`

Check today's API usage against tier limits.

No parameters required.

### `send_sms`

Send an outbound SMS from a rented number. $0.02 per message.

| Parameter | Type | Description |
|-----------|------|-------------|
| `from` | string | Your rented phone number |
| `to` | string | Destination number |
| `message` | string | SMS text |

### `get_deposit_address`

Get a crypto deposit address to fund your account.

| Parameter | Type | Description |
|-----------|------|-------------|
| `chain` | string | Blockchain: base, ethereum, solana, bitcoin, monero, etc. |

## Referral Program

Earn **10% commission** on all service fees from agents you refer. The commission is automatic — when a referred agent pays for any service, 10% is credited to your balance instantly.

1. Get your referral code from `referral_stats` or `register`
2. Share it with other agents
3. They register with `register(referral_code="YOUR_CODE")`
4. You earn 10% on everything they spend, forever

## Example Workflows

### Sign up for a service with email verification

```
1. create_identity(type="email")           → gets disposable address
2. [use the address to sign up for a service]
3. get_inbox(address="...", codes_only=true) → gets the OTP code
4. [enter the code to complete verification]
5. destroy_identity(type="email", identifier="...")
```

### One-call verification (recommended)

```
1. wait_for_otp(method="email")  → creates address, waits, returns code
2. [enter the code]
```

### SMS verification for a US service

```
1. create_identity(type="phone", country="US")  → gets phone number
2. [enter number on service]
3. get_sms(number="...", codes_only=true)        → gets OTP
4. destroy_identity(type="phone", identifier="...")
```

## Pricing

| Service | Cost |
|---------|------|
| Disposable email | $0.05 |
| Phone rental (10 min) | $0.30 |
| Phone rental (1 hour) | $0.50 |
| Phone rental (24 hours) | $1.00 |
| Phone rental (30 days) | $5.00 |
| Send SMS | $0.02 |
| Auto-verify (email) | $0.10 |
| Auto-verify (SMS) | $0.50 |
| **Free tier** | **5 emails + 2 SMS + 3 verifications per day** |

## License

MIT