aegis-x402-mcp
# aegis-x402-mcp
> **Model Context Protocol (MCP) server for [AegisAudit](https://aegisaudit.org) — Autonomous On-Chain Token Security, PreFlight Bundles, Honeypot Simulation, KYA Reputation, and Grounded AI over the x402 v2 Protocol on Base Mainnet.**
[](https://www.npmjs.com/package/aegis-x402-mcp)
[](https://opensource.org/licenses/MIT)
[-0052FF)](https://base.org)
[](https://x402.org)
`aegis-x402-mcp` connects Claude Desktop, Cursor, Windsurf, and autonomous trading bots directly to **[https://aegisaudit.org](https://aegisaudit.org)** (local `stdio` CLI or hosted Streamable HTTP at `https://aegisaudit.org/mcp`). Every paid response includes a third-party verifiable ECDSA `secp256k1` EIP-191 `proofOfExecution` receipt (`/.well-known/poe-key.json`), and upstream failures fail closed (`HTTP 502`, zero USDC charged).
- **Canonical Gateway:** `https://aegisaudit.org`
- **Hosted Streamable HTTP MCP:** `https://aegisaudit.org/mcp`
- **Contact:** `security@aegisaudit.org`
---
## Commercial Security SKUs & MCP Tools (8 Tools)
| Tool Name | Price | Description |
|---|---|---|
| `aegis_preflight_bundle` | **$0.20 USDC** | **Commercial SKU #1 (Flagship Pre-Swap Guard):** Atomic multi-oracle honeypot audit + DEX liquidity depth + AP2 spend mandate + counterparty KYA + ECDSA PoE receipt. |
| `aegis_priority_audit` | **$0.05 USDC** | **Commercial SKU #2:** 100% cache-bypassed, fresh live-oracle scan for sniper bots & new Base pool launches. |
| `aegis_token_audit` | **$0.01 USDC** | **Commercial SKU #3:** Multi-oracle smart contract bytecode inspection (GoPlus, Honeypot.is V2, DexScreener, Base RPC). |
| `aegis_wallet_kya` | **$0.01 USDC** | Know-Your-Agent (KYA) counterparty wallet reputation, transaction nonce age, balances, and OFAC/GoPlus sanctions checks. |
| `aegis_web_scrape` | **$0.005 USDC** | Converts any public webpage into clean, token-efficient LLM Markdown and extracted links. |
| `aegis_grounded_chat` | **$0.005 USDC** | OpenAI-compatible grounded LLM inference enriched with live Base/Ethereum on-chain security telemetry. |
| `aegis_token_preview` | **FREE** | Real-time market pool, token price, pair address, and DEX liquidity without payment. |
| `aegis_recent_audits` | **FREE** | Real-time stream of latest verified settled token audits across Base, Ethereum, and Solana. |
---
## Trading Bot & Sniper Guard Examples (`Base Mainnet`)
Drop-in fail-closed pre-swap gates calling `https://aegisaudit.org/api/v1/preflight/bundle` (`$0.20 USDC` over x402 v2) before submitting a swap on Aerodrome or Uniswap:
- TypeScript (`@x402/fetch` + `@x402/evm` + `viem`): [`examples/base-sniper-guard.ts`](examples/base-sniper-guard.ts)
- Python (zero external dependencies): [`examples/base-sniper-guard.py`](examples/base-sniper-guard.py)
Inspect a live sample clearance response with zero payment:
```bash
curl -s https://aegisaudit.org/api/v1/sample/preflight
```
---
## 3-Tier Frictionless Execution Architecture
1. **Tier 1 — Zero-Config (Free Tier):**
Tools like `aegis_token_preview` and `aegis_recent_audits` work instantly out-of-the-box with zero configuration or keys.
2. **Tier 2 — Prepaid Credit Token (Recommended for Humans):**
Top up in 1-click at [https://aegisaudit.org/pay](https://aegisaudit.org/pay) to get a signed 24-hour credit token `aegis_credit_...`.
Add `AEGIS_CREDIT_TOKEN` in your config. No local wallet key or per-call signing required.
3. **Tier 3 — Autonomous Agentic Wallet (For Autonomous Trading Bots & Power Users):**
Add `AEGIS_PRIVATE_KEY` in your config.
The local MCP client signs gasless EIP-3009 micro-settlements on Base Mainnet on-demand inside the MCP process. Keys never leave your machine.
**Security Allowlist Guard:** The client strictly verifies the recipient and refuses to sign toward any address other than the official Aegis node (`0x111ef680B6EFdd859FbEc473b907aCe95F0D1acB`).
---
## Quick Setup
### Option 1: Claude Desktop
Add this configuration to your `claude_desktop_config.json`:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"aegis-security": {
"command": "npx",
"args": ["-y", "aegis-x402-mcp"],
"env": {
"AEGIS_CREDIT_TOKEN": "aegis_credit_your_token_or_leave_empty_for_free_tier"
}
}
}
}
```
### Option 2: Cursor (`.cursor/mcp.json`)
Create or update `.cursor/mcp.json` in your project root:
```json
{
"mcpServers": {
"aegis-security": {
"command": "npx",
"args": ["-y", "aegis-x402-mcp"],
"env": {
"AEGIS_CREDIT_TOKEN": "aegis_credit_your_token"
}
}
}
}
```
### Option 3: Windsurf / Remote Streamable HTTP
Add to `~/.codeium/windsurf/mcp_config.json` (or connect any Streamable HTTP MCP client to `https://aegisaudit.org/mcp`):
```json
{
"mcpServers": {
"aegis-security": {
"command": "npx",
"args": ["-y", "aegis-x402-mcp"]
}
}
}
```
---
## Environment Variables
| Variable | Description |
|---|---|
| `AEGIS_GATEWAY_URL` | Gateway URL (defaults to `https://aegisaudit.org`). |
| `AEGIS_CREDIT_TOKEN` | Tier-bound 24h prepaid credit token generated from `/pay` or prior `X-Aegis-Credit-Token` settlement headers. |
| `AEGIS_PRIVATE_KEY` | Optional local EVM private key (`0x...`) used in-process to sign EIP-3009 USDC authorizations on Base without keys ever leaving your machine. |
| `AEGIS_API_KEY` | Alias for `AEGIS_CREDIT_TOKEN` / prepaid enterprise API key. |
| `X402_PAYMENT_HEADER` | Pre-signed base64 EIP-3009 payment header or authorization token. |
---
## Discovery & Registries
- **Canonical Docs & Agent Manifests:** [`aegisaudit.org/AGENTS.md`](https://aegisaudit.org/AGENTS.md) · [`aegisaudit.org/llms-full.txt`](https://aegisaudit.org/llms-full.txt) · [`aegisaudit.org/.well-known/x402.json`](https://aegisaudit.org/.well-known/x402.json)
- **Official MCP Registry:** [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io) (`io.github.Goatincrypto/aegis-x402-mcp`)
- **NPM:** [https://www.npmjs.com/package/aegis-x402-mcp](https://www.npmjs.com/package/aegis-x402-mcp)
- **GitHub:** [https://github.com/Goatincrypto/aegis-x402-mcp](https://github.com/Goatincrypto/aegis-x402-mcp)
- **Security Contact:** `security@aegisaudit.org`
---
## License
MIT © 2026 Antigravity Autonomous Systems
TDQS
Scored across 7 tools
Each tool targets a distinct capability tier: free preview, free audit stream, standard paid audit, priority audit, wallet reputation, web scraping, and a bundle. The only friction is the audit trio (token_audit, priority_audit, preflight_bundle), which overlap in purpose, but the cost/freshness/bundling cues in the descriptions mostly resolve the choice.
All names share the aegis_ prefix and snake_case with a resource-qualified style (aegis_token_audit, aegis_wallet_kya, aegis_web_scrape). The internal ordering varies slightly (adjective-first in priority_audit, noun-first elsewhere), but the pattern is predictable.
Seven tools is well within the ideal range and each earns its place: two free discovery tools, two paid audit tiers, wallet KYA, scraping, and an all-in-one bundle. No redundant or filler tools are present.
The surface covers the core pre-trade workflow: market preview, security audit, priority audit, counterparty KYA, and a combined bundle, plus web scraping for research. Minor gaps exist—no standalone AP2 spend-mandate tool (only inside the bundle) and no lookup of a historical audit for a specific token beyond the recent stream—but agents can work around these.