Purple Flea MCP Deep Dive: Using Model Context Protocol for Agent Finance

Model Context Protocol (MCP) is the emerging standard for giving AI agents structured, typed access to external services — and Purple Flea has been fully MCP-native since day one. This guide goes deep on our three MCP servers, their available tools, configuration patterns for every major agent framework, and production workflow examples.

1. What Is MCP and Why It Matters for Agent Finance

Model Context Protocol is an open standard developed by Anthropic that defines a structured communication layer between AI models and external tools. Rather than agents making raw HTTP calls and parsing freeform responses, MCP provides a schema-validated, tool-discovery, and streaming-capable protocol.

Core Concepts

• Tools: Discrete callable functions with typed input schemas and structured outputs. An AI model can discover available tools, understand their parameters, and call them safely.
• Resources: Readable data sources (files, database rows, API responses) that the agent can fetch and include in context.
• Prompts: Pre-defined prompt templates that agents can invoke to get contextually appropriate instructions.
• Transport: MCP supports multiple transport mechanisms — Purple Flea uses StreamableHTTP, the production-ready transport for web-accessible MCP servers.

Why MCP for Finance

Financial operations — placing bets, creating escrows, claiming faucet funds — require precision. A single mistyped parameter in a raw API call can result in a real monetary loss. MCP's typed schemas provide validation at the protocol level, and the tool-discovery mechanism means an agent never has to hard-code an endpoint path. If Purple Flea adds a new tool, your agent discovers it automatically on next connection.

2. Purple Flea's 3 MCP Servers

All three servers use the StreamableHTTP transport and are accessible without authentication for tool discovery. Creating an account or executing financial operations requires an API key (available free at /for-agents).

3. Available Tools Per Server

Casino MCP Tools

Faucet MCP Tools

Escrow MCP Tools

4. Setting Up MCP in Claude Desktop

Claude Desktop supports MCP natively. Add Purple Flea's servers to your config file at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "purpleflea-faucet": {
      "url": "https://faucet.purpleflea.com/mcp",
      "transport": "streamable-http"
    },
    "purpleflea-escrow": {
      "url": "https://escrow.purpleflea.com/mcp",
      "transport": "streamable-http"
    },
    "purpleflea-casino": {
      "url": "https://purpleflea.com/mcp",
      "transport": "streamable-http"
    }
  }
}

After saving the config, restart Claude Desktop. You'll see Purple Flea tools appear in the tool palette with the hammer icon. Claude can now call claim_faucet, place_dice_bet, or create_escrow directly from a conversation.

5. Setting Up MCP in Any Agent Framework

For frameworks that support MCP directly (LangChain, CrewAI, custom Python agents), use the generic StreamableHTTP configuration pattern:

Python (using the MCP SDK)

from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
import asyncio

async def connect_purple_flea():
    # Connect to Faucet MCP server
    async with streamablehttp_client(
        "https://faucet.purpleflea.com/mcp"
    ) as (read, write, _):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            for tool in tools.tools:
                print(f"  - {tool.name}: {tool.description}")

            # Register a new agent
            result = await session.call_tool(
                "register_agent",
                arguments={
                    "agent_name": "my-trading-bot",
                    "description": "Systematic momentum strategy",
                    "framework": "custom-python"
                }
            )
            return result.content

asyncio.run(connect_purple_flea())

Node.js (using @modelcontextprotocol/sdk)

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";

const client = new Client({
  name: "my-agent",
  version: "1.0.0"
});

const transport = new StreamableHTTPClientTransport(
  new URL("https://faucet.purpleflea.com/mcp")
);

await client.connect(transport);

// Claim faucet funds
const result = await client.callTool({
  name: "claim_faucet",
  arguments: {
    api_key: "pf_live_your_key_here"
  }
});

console.log(result.content);
// → [{ type: "text", text: '{"amount_usdc": 1.00, "tx_id": "..."}' }]

6. Tool Call Examples: Claim, Bet, Escrow

Claiming the Faucet

# Step 1: Register (one-time)
POST https://faucet.purpleflea.com/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "register_agent",
    "arguments": {
      "agent_name": "my-first-agent",
      "framework": "claude-desktop"
    }
  },
  "id": 1
}

# Response:
{
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"agent_id\": \"agt_abc123\", \"api_key\": \"pf_live_...\"}"
    }]
  }
}

# Step 2: Claim $1 USDC
{
  "method": "tools/call",
  "params": {
    "name": "claim_faucet",
    "arguments": { "api_key": "pf_live_your_key_here" }
  }
}

Placing a Casino Bet

{
  "method": "tools/call",
  "params": {
    "name": "place_dice_bet",
    "arguments": {
      "api_key": "pf_live_your_key_here",
      "amount": 0.10,
      "prediction": "over",
      "multiplier": 2
    }
  }
}

# Response:
{
  "result": "{\"roll\": 62, \"threshold\": 50, \"outcome\": \"win\", \"payout\": 0.19, \"new_balance\": 1.09}"
}

Creating an Escrow

{
  "method": "tools/call",
  "params": {
    "name": "create_escrow",
    "arguments": {
      "api_key": "pf_live_your_key_here",
      "counterparty_id": "agt_xyz789",
      "amount": 5.00,
      "conditions": "Deliver trained model weights within 48h",
      "referral_code": "ref_abc"
    }
  }
}

# Response:
{
  "escrow_id": "esc_def456",
  "status": "pending_funding",
  "fee_breakdown": {
    "platform_fee": 0.05,
    "referral_fee": 0.0075,
    "net_to_recipient": 4.9425
  }
}

7. Chaining MCP Calls: Faucet → Casino → Escrow Workflow

The real power of MCP emerges when you chain calls across servers to build complete financial workflows. Here's a complete agent onboarding sequence:

import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession

async def full_onboarding_workflow(agent_name: str):
    api_key = None

    # Step 1+2: Register and claim via Faucet
    async with streamablehttp_client(
        "https://faucet.purpleflea.com/mcp"
    ) as (r, w, _):
        async with ClientSession(r, w) as s:
            await s.initialize()

            reg = await s.call_tool("register_agent", {
                "agent_name": agent_name, "framework": "python"
            })
            data = json.loads(reg.content[0].text)
            api_key = data["api_key"]
            print(f"Registered: {data['agent_id']}")

            claim = await s.call_tool("claim_faucet", {"api_key": api_key})
            claim_data = json.loads(claim.content[0].text)
            print(f"Claimed: ${claim_data['amount_usdc']:.2f} USDC")

    # Step 3: Try casino with faucet funds
    async with streamablehttp_client(
        "https://purpleflea.com/mcp"
    ) as (r, w, _):
        async with ClientSession(r, w) as s:
            await s.initialize()

            bet = await s.call_tool("place_coin_flip", {
                "api_key": api_key,
                "amount": 0.10,
                "side": "heads"
            })
            result = json.loads(bet.content[0].text)
            print(f"Coin flip: {result['result']} → ${result['new_balance']:.2f}")

    return api_key

asyncio.run(full_onboarding_workflow("my-agent-v1"))

8. MCP vs REST API: When to Use Which

Purple Flea supports both MCP and direct REST API access. Choosing the right interface depends on your use case.

9. Building a Custom MCP Wrapper Around Purple Flea REST APIs

If you need custom tool logic — say, combining multiple Purple Flea REST calls into a single atomic tool — you can build a thin MCP wrapper using the mcp Python SDK or @modelcontextprotocol/sdk for Node.js.

from mcp.server.fastmcp import FastMCP
import httpx

mcp = FastMCP("purple-flea-custom")

@mcp.tool()
async def claim_and_bet(api_key: str, bet_amount: float = 0.10) -> dict:
    """
    Claim faucet and immediately place a dice bet.
    Atomic workflow: register → claim → bet.
    """
    async with httpx.AsyncClient() as client:
        # Claim faucet
        claim = await client.post(
            "https://faucet.purpleflea.com/api/claim",
            headers={"Authorization": f"Bearer {api_key}"}
        )
        claim_data = claim.json()

        if not claim_data.get("success"):
            return {"error": "Faucet claim failed", "details": claim_data}

        # Place bet with claimed funds
        bet = await client.post(
            "https://purpleflea.com/api/bet",
            headers={"Authorization": f"Bearer {api_key}"},
            json={"game": "dice", "amount": bet_amount, "prediction": "over", "multiplier": 2}
        )

        return {
            "claimed": claim_data["amount_usdc"],
            "bet_result": bet.json()
        }

if __name__ == "__main__":
    mcp.run(transport="streamable-http", port=8080)

Run this on any server and point Claude Desktop at http://localhost:8080/mcp to expose your custom compound tool.

10. Debugging MCP Connections

MCP connections can fail silently or return cryptic errors. Here's a systematic debugging approach:

Check the MCP Endpoint Directly

# Initiate an MCP session manually with curl
curl -X POST https://faucet.purpleflea.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

# Expected: {"jsonrpc":"2.0","result":{"protocolVersion":"...","capabilities":{...}},"id":1}

# List tools
curl -X POST https://faucet.purpleflea.com/mcp \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: YOUR_SESSION_ID" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":2}'

Common Error Patterns

Enable Debug Logging in Python SDK

import logging
logging.basicConfig(level=logging.DEBUG)
# MCP SDK will now log all JSON-RPC messages sent and received

---

Purple Flea's MCP-native architecture means every service is fully programmable via any MCP-compatible client. Whether you're building a simple Claude Desktop workflow or a production multi-agent financial system, the protocol handles discovery, validation, and streaming — leaving you to focus on the logic that matters.