# agent-insurance-mcp-server

**MCP server for AI agent transaction insurance and escrow** — protect agent-to-agent payments with smart escrow, dispute resolution, and risk scoring.

[![PyPI version](https://badge.fury.io/py/agent-insurance-mcp-server.svg)](https://pypi.org/project/agent-insurance-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## What it does

When AI agents transact with each other — paying for data, code, analysis, or content — there's no guarantee of delivery. This server adds a **trust layer**:

1. Buyer agent creates an escrow → funds are locked
2. Seller agent completes the task
3. Buyer agent releases escrow → seller receives payment
4. If something goes wrong → dispute opens, auto-verdict runs

## Tools (11)

| Tool | Description |
|------|-------------|
| `create_escrow` | Lock funds between buyer/seller agent for a task |
| `release_escrow` | Release funds after task completion (success/partial) |
| `open_dispute` | Open a dispute if something goes wrong |
| `get_insurance_quote` | Get risk score + premium before transacting |
| `process_claim` | Resolve a dispute (buyer_wins/seller_wins/split) |
| `get_escrow_status` | Check current status and all details of an escrow |
| `get_insurance_info` | System stats: active escrows, disputes, protected amounts |
| `list_escrows` | **NEW** Browse and filter all escrows (by status, agent, etc.) |
| `get_agent_history` | **NEW** Full transaction history + trust score for any agent |
| `auto_resolve_expired` | **NEW** Automatically resolve expired escrows (buyer refund) |
| `insurance_analytics` | **NEW** System analytics: volume, risk distribution, top agents |

## Installation

```bash
pip install agent-insurance-mcp-server
```

## Claude Desktop Configuration

```json
{
  "mcpServers": {
    "agent-insurance": {
      "command": "agent-insurance-mcp-server"
    }
  }
}
```

## Example Usage

```python
# 1. Get a quote first
quote = get_insurance_quote(
    buyer_agent_id="agent_buyer_001",
    seller_agent_id="agent_coder_007",
    amount=100.0,
    task_type="code"
)
# → risk_score: 35, premium: 2.8%, premium_amount: 2.80

# 2. Create escrow
escrow = create_escrow(
    buyer_agent_id="agent_buyer_001",
    seller_agent_id="agent_coder_007",
    amount=100.0,
    task_description="Build a REST API endpoint for user authentication",
    deadline_hours=48
)
# → escrow_id: "escrow_abc123def456", status: "active"

# 3a. Release on success
result = release_escrow(
    escrow_id="escrow_abc123def456",
    outcome="success"
)
# → seller_payout: 100.0, buyer_refund: 0.0

# 3b. Or open a dispute
dispute = open_dispute(
    escrow_id="escrow_abc123def456",
    reason="Task not delivered as agreed — API is missing auth logic"
)
# → auto_verdict: "buyer_favored", buyer_protection: 80%

# 4. Check agent trust (NEW in v0.2.0)
history = get_agent_history(agent_id="agent_coder_007")
# → trust_score: 72, completion_rate: 90%, dispute_rate: 5%
```

## How Risk Scoring Works

- **Base risk:** 30 points
- **Seller dispute history:** +0-40 points based on past disputes
- **Transaction size:** +5-15 points for large amounts
- **Experience bonus:** -2 points per completed escrow (max -20)
- **Premium range:** 1-5% of transaction amount

## Changelog

### v0.2.0 (April 2026)
- 4 new tools: `list_escrows`, `get_agent_history`, `auto_resolve_expired`, `insurance_analytics`
- Agent trust scoring (0-100) based on transaction history
- Expired escrow auto-resolution with buyer refund
- System-wide analytics (volume, risk distribution, top agents)
- 11 tools total (up from 7)

### v0.1.0
- Initial release with 7 core tools

## Related MCP Servers

- [agent-staking-mcp-server](https://pypi.org/project/agent-staking-mcp-server/) — Agent reputation staking
- [agent-reputation-mcp-server](https://pypi.org/project/agent-reputation-mcp-server/) — Agent trust scores
- [x402-mcp-server](https://pypi.org/project/x402-mcp-server/) — Agent micropayments

## License

MIT — built by [AiAgentKarl](https://github.com/AiAgentKarl)