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

pip install proxell-mcp

Claude Desktop

Add to your claude_desktop_config.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:

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

Python SDK

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

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

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:

{
  "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:

# 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 for backend setup instructions.

---

Documentation

• Full API Reference
• PXP Protocol Specification
• Agent Integration Guide
• Self-Hosting Guide

---

License

MIT -- see LICENSE for details.