# ATXP MCP Direct API Reference

## Authentication
ALL MCP endpoints accept:
```
Authorization: Bearer https://accounts.atxp.ai?connection_token=TOKEN&account_id=ACCT_ID
Accept: application/json, text/event-stream
Content-Type: application/json
```

Token is NOT bound to account_id — cross-account calls work for MCP (but LLM Gateway checks account_id).

## Request Format (JSON-RPC 2.0)
```json
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "TOOL_NAME", "arguments": {}}}
```

## Endpoints & Pricing (2026-06-25)

### Email (`email.mcp.atxp.ai`)
| Tool | Price | Status |
|------|-------|--------|
| email_check_inbox | FREE | ✅ Works on all 50 accs |
| email_send_email | $0.01 | Requires payment request |
| email_search | — | Not tested |
| email_delete | FREE | ✅ |
| email_get_message | FREE | ✅ |
| email_get_attachment | FREE | ✅ |
| email_claim_username | — | Not tested |
| email_release_username | — | Not tested |

### Phone (`phone.mcp.atxp.ai`)
| Tool | Price | Status |
|------|-------|--------|
| phone_check_sms | FREE | ✅ Works on all 50 accs |
| phone_send_sms | $0.01 | Requires payment request |
| phone_register | $2.00 | Requires payment request |
| phone_configure_voice | — | Not tested |
| phone_call | — | Not tested |
| phone_check_calls | — | Not tested |
| phone_get_call | — | Not tested |
| phone_get_attachment | — | Not tested |
| phone_search | — | Not tested |
| phone_release | — | Not tested |
| phone_mark_read | — | Not tested |

### Search (`search.mcp.atxp.ai`)
| Tool | Price | Status |
|------|-------|--------|
| search_search | $0.01 | Requires payment request |

### Image (`image.mcp.atxp.ai`)
| Tool | Price | Status |
|------|-------|--------|
| image_create_image | $0.201 | Requires payment request |
| image_create_image_async | $0.201 | Requires payment request |

## Payment Request Handling
When a tool requires payment, response includes:
```json
{
  "error": {
    "code": -30402,
    "message": "Payment via ATXP is required. You will be charged 0.01. Please pay at: https://auth.atxp.ai/payment-request/XXX",
    "data": {
      "paymentRequestUrl": "https://auth.atxp.ai/payment-request/XXX",
      "chargeAmount": "0.01"
    }
  }
}
```
Payment request URL returns JSON with destination addresses (Base USDC, ATXP internal, Solana, Polygon, World).

## Response Format
SSE stream: `event: message\ndata: {...}\n`. Parse by splitting on `\n` and checking for lines starting with `data: `.

## Health Checks
- `https://email.mcp.atxp.ai/health` → `{"status":"ok"}`
- `https://phone.mcp.atxp.ai/health` → `{"status":"ok"}`
- Search/image MCP: health endpoint returns 404

## Parallel Spam Pattern (Python)
```python
import json, urllib.request, threading

def check_inbox(acc):
    auth = f'https://accounts.atxp.ai?connection_token={acc["token"]}&account_id={acc["id"]}'
    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "email_check_inbox", "arguments": {}}}).encode()
    req = urllib.request.Request("https://email.mcp.atxp.ai/", data=body, headers={
        "Content-Type": "application/json", "Accept": "application/json, text/event-stream",
        "Authorization": f"Bearer {auth}"
    })
    with urllib.request.urlopen(req, timeout=10) as r:
        # parse SSE response
        pass

threads = [threading.Thread(target=check_inbox, args=(acc,)) for acc in pool]
for t in threads: t.start()
for t in threads: t.join()
```