<div align="center">

# 🛡️ AEGIS MCP Server

### The agent control plane for private, pay-per-request internet access

Give any AI agent its own **privacy layer + payment rail** — route HTTP through residential & datacenter exit nodes, pay per request in USDC on Solana, and govern its own budget and keys, all from inside Claude, Cursor, or any MCP client.

[![npm](https://img.shields.io/npm/v/@aegisprivacy/mcp?color=000&label=%40aegisprivacy%2Fmcp)](https://www.npmjs.com/package/@aegisprivacy/mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-000.svg)](./LICENSE)
[![Model Context Protocol](https://img.shields.io/badge/MCP-server-000)](https://modelcontextprotocol.io)
[![Solana](https://img.shields.io/badge/settled%20on-Solana-000)](https://solana.com)

[Website](https://aegisprivacy.org) · [Get an API key](https://aegisprivacy.org/agent) · [Docs](https://aegisprivacy.org/docs) · [X](https://x.com/privacyaegis) · [Telegram](https://t.me/AegisPrivacy)

</div>

---

## What is this?

**AEGIS** is privacy infrastructure for the open internet — a residential/datacenter proxy + VPN where humans and **autonomous agents** route traffic through operator-run exit nodes and pay **per request** in USDC, settled on Solana. No logs. No KYC.

This package exposes AEGIS as a **Model Context Protocol** server, so an agent can run its *entire* lifecycle without leaving the chat:

- 🌐 **Fetch through a privacy node** — hide the agent's origin IP, pick an exit country, choose residential / datacenter / mobile.
- 💸 **Pay as it goes** — ~$0.001 USDC per request from a prepaid balance, or auto‑settle on‑chain with `pay‑and‑retry` when the balance hits zero.
- 🔑 **Govern its own budget** — mint capped, geo/time‑scoped child keys for sub‑agent swarms (AP2‑style mandates), rotate and revoke them.
- 📊 **Audit its own spend** — usage, request history, live network stats, and (if it runs a node) earnings.

Every tool is a thin, audited wrapper over a public AEGIS REST endpoint. **No secrets are baked in** — you bring your own API key (and, optionally, a funded wallet) via environment variables.

---

## Quickstart

### Claude Desktop

Add to `claude_desktop_config.json`:

```jsonc
{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@aegisprivacy/mcp"],
      "env": {
        "AEGIS_API_KEY": "aegis_your_key_here"
      }
    }
  }
}
```

Grab a key at **[aegisprivacy.org/agent](https://aegisprivacy.org/agent)**, restart Claude, and ask it to *"fetch example.com through a German residential node."*

### Cursor / other MCP clients

Point any MCP‑capable client at the same `npx -y @aegisprivacy/mcp` command with `AEGIS_API_KEY` in the environment.

---

## Configuration

| Variable | Required | Default | Description |
|---|:---:|---|---|
| `AEGIS_API_KEY` | ✅ | — | Your key from [aegisprivacy.org/agent](https://aegisprivacy.org/agent). |
| `AEGIS_WALLET_SECRET` | — | _(off)_ | A funded Solana wallet (base58 or JSON array). **Setting this opts into autonomous spending**: a `402` (empty balance) is settled on‑chain and the request is retried automatically. |
| `AEGIS_AUTO_TOPUP_USDC` | — | `1` | USDC amount per automatic top‑up. |
| `AEGIS_SOLANA_RPC` | — | `api.mainnet-beta.solana.com` | Solana RPC endpoint for settlement. |
| `AEGIS_BASE_URL` | — | `https://aegisprivacy.org` | API base URL. |

> **Spending is opt‑in.** Without `AEGIS_WALLET_SECRET`, an empty balance simply surfaces a `402` with top‑up instructions — the agent can never spend on‑chain unless you hand it a funded wallet.

---

## The toolbox (19 tools)

#### 🌐 Routing
| Tool | What it does |
|---|---|
| `aegis_fetch` | Privacy‑routed HTTP request (any method, country, ip_class). |
| `aegis_get` / `aegis_post` | Convenience GET / POST shorthands. |
| `aegis_fetch_with_receipt` | Fetch + return settlement metadata and the no‑log receipt signature. |

#### 💸 Balance & cost
| Tool | What it does |
|---|---|
| `aegis_balance` | Remaining prepaid USDC (+ credits). |
| `aegis_estimate_cost` | Local estimate for a planned batch — spends nothing. |

#### 📡 Network
| Tool | What it does |
|---|---|
| `aegis_list_countries` | Exit countries with online nodes + available ip_classes. |
| `aegis_network_stats` | Live nodes, countries, requests & bytes served. |

#### 📊 Self‑audit
| Tool | What it does |
|---|---|
| `aegis_agent_stats` | This key's requests & USDC spend (today / week / total) + rate budget. |
| `aegis_request_history` | Recent routed requests (URL, country, cost, status, bytes). |

#### 🔑 Key governance
| Tool | What it does |
|---|---|
| `aegis_list_keys` / `aegis_key_tree` | List keys flat, or as a budget tree with mandates + rolled‑up spend. |
| `aegis_mint_key` | Mint a **child** key with an AP2‑style mandate (lifetime/daily/monthly USDC caps, country/ip_class lock, expiry). A child can only *narrow* its parent. |
| `aegis_set_spend_cap` · `aegis_rename_key` · `aegis_revoke_key` · `aegis_rotate_key` | Manage caps, labels, revocation, and credential rotation. |

#### ⚙️ Operator (if you run a node)
| Tool | What it does |
|---|---|
| `aegis_operator_earnings` | Session + request counts and estimated USDC earnings. |
| `aegis_operator_history` | Daily earnings & request history (last N days). |

---

## Example prompts

> *"Use AEGIS to GET `https://api.ipify.org` through a residential node in Japan and tell me the exit IP."*

> *"Mint a child key labeled `scraper` capped at $5 lifetime, locked to US datacenter, expiring in 24h — then show me the key tree."*

> *"Estimate the cost of 2,000 requests, check my balance, and tell me if I can afford it."*

---

## How it works

```
  AI agent (Claude / Cursor)
        │  MCP (stdio)
        ▼
  @aegisprivacy/mcp  ──►  aegisprivacy.org  ──►  exit node (residential / datacenter)
        │   Bearer API key        x402 per‑request billing        │
        │                         metered in USDC                 ▼
        └── optional wallet ── 402? settle USDC on Solana ── retry & serve
```

The server holds no privileged state — it authenticates with your API key and (optionally) signs USDC settlements with your wallet. All billing, node selection, and metering happen server‑side on the AEGIS network.

---

## Development

```bash
npm install
npm run build      # tsc → dist/
npm start          # run the stdio server
```

Requires Node ≥ 18.

---

## License

[MIT](./LICENSE) © AEGIS Privacy

<div align="center">
<sub>Private by default — no logs, no KYC, settled on Solana.</sub>
</div>