# Proxell MCP Server

**The AI-native digital asset exchange protocol.** 93 tools. 6 asset types. One protocol.

Proxell implements **PXP (Proxell Exchange Protocol)** -- a structured protocol that enables AI agents to autonomously discover, price, negotiate, trade, and settle digital assets. Connect any MCP-compatible client (Claude, GPT, custom agents) to a live marketplace where agents buy, sell, and broker deals without human intervention.

---

## What is PXP?

PXP/1.0 is a four-phase transaction protocol designed for machine-to-machine commerce:

```
DISCOVER --> QUOTE --> RESERVE --> TRANSACT --> RECEIPT --> ACKNOWLEDGE
                |                     |
                +-- NEGOTIATE --------+-- DISPUTE --> RESOLVE
```

Every verb returns structured JSON with `ok`, `protocol`, `version`, and `data` fields -- purpose-built for LLM consumption. No HTML parsing. No guessing. Agents know exactly what happened and what to do next.

### Supported Asset Types

| Type | Description | Example |
|------|-------------|---------|
| `lead` | Sales leads with enrichment data | Contact records, firmographics |
| `dataset` | Structured data files | CSV exports, research datasets |
| `api` | API access credentials | Enrichment APIs, scoring endpoints |
| `model` | Machine learning models | PyTorch classifiers, ONNX models |
| `code` | Code repositories and templates | GitHub repos, boilerplate |
| `media` | Images, video, audio | Stock photos, training data |

---

## Quick Start

### Installation

```bash
pip install proxell-mcp
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "proxell": {
      "command": "proxell-mcp",
      "env": {
        "PXL_PROXELL_API_URL": "https://api.proxell.io",
        "PXL_PROXELL_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Cursor / Windsurf / Any MCP Client

Connect via Streamable HTTP:

```json
{
  "mcpServers": {
    "proxell": {
      "url": "https://api.proxell.io/mcp",
      "headers": {
        "Authorization": "Bearer your-api-key"
      }
    }
  }
}
```

### Python SDK

```python
from fastmcp import Client

async with Client("https://api.proxell.io/mcp") as client:
    # Discover what's available
    result = await client.call_tool("pxp_discover")

    # Instant buy a lead
    purchase = await client.call_tool("exchange_instant", {
        "asset_type": "lead",
        "max_price": 25.00,
        "min_quality": 70,
        "prefer": "best_quality"
    })

    # List a dataset for sale
    listing = await client.call_tool("list_and_price", {
        "asset_type": "dataset",
        "data": {
            "name": "US SaaS Decision Makers",
            "format": "csv",
            "row_count": 50000,
            "columns": [
                {"name": "email", "type": "string"},
                {"name": "company", "type": "string"},
                {"name": "title", "type": "string"},
                {"name": "revenue", "type": "number"}
            ]
        },
        "exclusivity": "shared"
    })
```

### JavaScript / TypeScript

```typescript
import { MCPClient } from "@anthropic-ai/mcp";

const client = new MCPClient("https://api.proxell.io/mcp", {
  headers: { Authorization: "Bearer your-api-key" },
});

// Run a full negotiation
const negotiation = await client.callTool("pxp_negotiate", {
  listing_id: "abc-123",
  offer_price: 15.0,
  action: "offer",
});

// Auto-negotiate with constraints
const deal = await client.callTool("negotiate_auto", {
  buyer_constraints: { max_price: 20, min_quality: 80 },
  seller_constraints: { min_price: 10, max_discount: 0.3 },
  asset_type: "lead",
  listing_id: "abc-123",
});
```

### cURL

```bash
curl -X POST https://api.proxell.io/mcp \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "pxp_status",
      "arguments": {}
    },
    "id": 1
  }'
```

---

## Tools (93 total)

### PXP Protocol Core (14 tools)

The heart of Proxell. Structured verbs for the complete transaction lifecycle.

| Tool | Description |
|------|-------------|
| `pxp_discover` | Find available asset types and marketplace statistics |
| `pxp_quote` | Get a price quote without listing (dry-run pricing) |
| `pxp_quote_listing` | Persist a quote against an active listing |
| `pxp_quote_status` | Fetch the current state of a persisted quote |
| `pxp_reserve` | Convert an open quote into an active reservation |
| `pxp_reservation_status` | Fetch the current state of a reservation |
| `pxp_negotiate` | Multi-round negotiation with strategy suggestions |
| `pxp_negotiation_status` | Check negotiation state with full history |
| `pxp_transact` | Execute purchase with credit hold and settlement |
| `pxp_receipt` | Get transaction receipt with delivery credentials |
| `pxp_acknowledge` | Buyer acknowledges successful delivery |
| `pxp_dispute` | Open a dispute against a transaction |
| `pxp_resolve_dispute` | Resolve a dispute and update transaction state |
| `pxp_status` | Protocol version, supported types, network stats |

### Instant Trading (3 tools)

One-call convenience tools for fast flows.

| Tool | Description |
|------|-------------|
| `exchange_instant` | Buy matching assets in one call (best_quality / cheapest / best_value) |
| `list_and_price` | Validate, assess quality, price, and list in one call |
| `exchange_batch` | Execute multiple list/buy/quote operations atomically |

### Exchange Marketplace (6 tools)

| Tool | Description |
|------|-------------|
| `listing_create` | Create a new listing on the exchange |
| `listing_search` | Search listings by asset type, score, price, industry |
| `asset_types_list` | List all registered asset types with schemas |
| `bid_place` | Place a bid on a listing (instant buy if price matches) |
| `bid_accept` | Accept a pending bid, triggering settlement |
| `transaction_settle` | Settle a completed transaction |

### Lead Management (4 tools)

| Tool | Description |
|------|-------------|
| `lead_create` | Create a new lead record |
| `lead_bulk_import` | Import up to 200 leads per call |
| `lead_search` | Search leads by company, industry, geography, stage, score |
| `lead_get` | Get full lead details by ID |

### Data Enrichment (5 tools)

| Tool | Description |
|------|-------------|
| `enrich_contact` | Enrich a contact via best available provider |
| `enrich_company` | Enrich a company by domain (firmographics, tech stack) |
| `enrich_waterfall` | Multi-provider waterfall enrichment with source attribution |
| `find_email` | Find email from name + company domain |
| `find_phone` | Find direct phone number for a contact |

### Lead Scoring (4 tools)

| Tool | Description |
|------|-------------|
| `score_lead` | ML + rule-based lead scoring |
| `score_explain` | Feature-level score breakdown |
| `predict_conversion` | Conversion probability + recommended next action |
| `score_batch` | Score up to 200 leads per call |

### Campaign & Outreach (5 tools)

| Tool | Description |
|------|-------------|
| `sequence_create` | Create an outreach sequence for a lead |
| `step_add` | Add steps (email, LinkedIn, phone, SMS) |
| `campaign_execute` | Execute pending steps across sequences |
| `campaign_pause` | Pause all active sequences |
| `reply_handle` | Classify reply intent and route accordingly |

### Compliance & GDPR (4 tools)

| Tool | Description |
|------|-------------|
| `consent_verify` | Check CAN-SPAM, GDPR, CCPA, TCPA compliance |
| `suppression_check` | Check suppression lists |
| `gdpr_request` | Handle access, erasure, portability, rectification |
| `audit_trail` | Query the full compliance audit log |

### Analytics & Reporting (5 tools)

| Tool | Description |
|------|-------------|
| `funnel_stats` | Lead funnel statistics with conversion rates |
| `roi_report` | Campaign and platform ROI calculation |
| `conversion_track` | Track conversion events |
| `pipeline_health` | Overall pipeline health and anomaly detection |
| `pxp_network_stats` | Network-wide transaction and volume statistics |

### Billing & Credits (5 tools)

| Tool | Description |
|------|-------------|
| `credits_balance` | Current credit balance and auto-refill settings |
| `credits_topup` | Top up credits (redirects to Stripe Checkout) |
| `usage_report` | Usage breakdown by tool, agent, and campaign |
| `invoice_get` | Invoice details and spend summary |
| `api_usage` | Daily/monthly API quota and usage |

### Agent Identity (4 tools)

| Tool | Description |
|------|-------------|
| `register_agent` | Create a portable agent identity wallet |
| `agent_profile` | Read agent profile (reputation, transaction history) |
| `agent_wallet` | Export signed portable wallet credential |
| `verify_agent_wallet` | Verify a wallet credential signature |

### Escrow & Settlement (4 tools)

| Tool | Description |
|------|-------------|
| `escrow_create` | Lock funds with machine-evaluable conditions |
| `escrow_status` | Evaluate conditions and return escrow state |
| `escrow_release` | Force release with satisfied evidence |
| `escrow_dispute` | Place escrow into disputed state |

### Subscriptions (4 tools)

| Tool | Description |
|------|-------------|
| `subscribe` | Create a metered subscription (per_unit / flat_rate / tiered) |
| `meter_usage` | Record usage against a subscription |
| `subscription_status` | Current spend, units consumed, state |
| `unsubscribe` | Cancel an active subscription |

### Pipeline Automation (6 tools)

| Tool | Description |
|------|-------------|
| `create_pipeline` | Create a persistent automation pipeline |
| `list_pipelines` | List active pipelines |
| `deactivate_pipeline` | Deactivate a pipeline |
| `pipeline_create` | Define a composable transaction pipeline |
| `pipeline_status` | Fetch pipeline and execution status |
| `pipeline_step` | Fetch a single pipeline step by index |

### Federation (5 tools)

| Tool | Description |
|------|-------------|
| `peer_register` | Register a federated PXP peer exchange |
| `federated_search` | Query local + remote exchanges simultaneously |
| `federated_transact` | Initiate cross-exchange bridge transactions |
| `peer_status` | Check peer health and trust score |
| `peer_list` | List all registered federated peers |

### Constraint Negotiation (1 tool)

| Tool | Description |
|------|-------------|
| `negotiate_auto` | Fast constraint-based machine negotiation (up to 200 rounds) |

### Situational Awareness (3 tools)

| Tool | Description |
|------|-------------|
| `pxp_my_status` | Tenant dashboard (listings, transactions, revenue, spend) |
| `pxp_explain` | Explain quality, pricing, and compliance for a transaction |
| `pxp_what_can_i_trade` | Discover asset types with schemas and examples |

### Asset Verticals (8 tools)

| Tool | Description |
|------|-------------|
| `dataset_register` | Register and list a dataset |
| `dataset_search` | Search datasets by tags, format, row count |
| `dataset_preview` | Preview first 5 rows before purchase |
| `register_api_asset` | Register and list an API |
| `query_api_assets` | Search APIs by auth type, rate limit |
| `register_code_asset` | Register and list code/repos |
| `query_code_assets` | Search code by language, coverage |
| `register_model_asset` | Register and list ML models |
| `query_model_assets` | Search models by framework, accuracy |
| `register_media_asset` | Register and list media (image/video/audio) |
| `query_media_assets` | Search media by type, resolution |

---

## Authentication

Proxell supports three authentication methods, resolved in priority order:

1. **JWT Bearer Token** -- Full tenant context with role-based access
2. **Scoped API Keys** -- Fine-grained permissions per asset type and action
3. **Tenant ID** -- Direct tenant identification (development only)

Pass credentials via MCP metadata:

```json
{
  "auth_token": "eyJhbGciOi...",
  "api_key": "pxl_live_...",
  "tenant_id": "uuid"
}
```

---

## Transport

Proxell MCP runs on **Streamable HTTP** (port 8100 by default):

- Stateless HTTP transport for horizontal scaling
- JSON responses optimized for LLM consumption
- Idempotency keys on all write operations
- Structured PXP error payloads with fix suggestions and related tool hints

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PXL_PROXELL_API_URL` | `https://api.proxell.io` | Proxell backend URL |
| `PXL_PROXELL_API_KEY` | | Your API key |
| `PXL_MCP_HOST` | `0.0.0.0` | MCP server bind host |
| `PXL_MCP_PORT` | `8100` | MCP server port |
| `PXL_ENVIRONMENT` | `development` | `development`, `testing`, `production` |

---

## Architecture

```
+------------------+       +------------------+       +------------------+
|  Claude Desktop  |       |   Custom Agent   |       |   Other Client   |
|  Cursor / VS Code|       |   (Python/JS)    |       |   (Any MCP)      |
+--------+---------+       +--------+---------+       +--------+---------+
         |                          |                          |
         +------------- MCP (Streamable HTTP) ----------------+
                                    |
                        +-----------+-----------+
                        |   Proxell MCP Server  |
                        |   93 tools / PXP/1.0  |
                        +-----------+-----------+
                                    |
                        +-----------+-----------+
                        |   Proxell Backend     |
                        |   PostgreSQL + Redis  |
                        |   Stripe + Enrichment |
                        +-----------------------+
```

---

## Self-Hosting

To run your own Proxell instance:

```bash
# Clone and install
git clone https://github.com/cvsper/proxell-mcp.git
cd proxell-mcp
pip install -e .

# Configure
export PXL_PROXELL_API_URL=http://localhost:8000
export PXL_PROXELL_API_KEY=your-key

# Run
proxell-mcp
```

The MCP server connects to a running Proxell backend. See the [full deployment guide](https://docs.proxell.io/deploy) for backend setup instructions.

---

## Documentation

- [Full API Reference](https://docs.proxell.io/api)
- [PXP Protocol Specification](https://docs.proxell.io/pxp)
- [Agent Integration Guide](https://docs.proxell.io/agents)
- [Self-Hosting Guide](https://docs.proxell.io/deploy)

---

## License

MIT -- see [LICENSE](LICENSE) for details.