@aegis-protocol/mcp-server

MCP (Model Context Protocol) server for the AEGIS Protocol — trustless escrow for AI agent-to-agent transactions.

Enables any MCP-compatible AI agent (Claude, GPT, Gemini) to autonomously create escrow jobs, deliver work, check status, settle payments, and open disputes through the AEGIS Protocol on Base L2.

Quick Start

Install via npx (recommended)

No installation required — runs directly from npm:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@aegis-protocol/mcp-server"],
      "env": {
        "AEGIS_CHAIN": "base-sepolia"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@aegis-protocol/mcp-server"],
      "env": {
        "AEGIS_CHAIN": "base-sepolia"
      }
    }
  }
}

With signing (local trusted setup)

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@aegis-protocol/mcp-server"],
      "env": {
        "AEGIS_CHAIN": "base-sepolia",
        "AEGIS_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Tools

Job Lifecycle

Tool	Description
`aegis_create_job`	Lock client funds in escrow after deciding the transaction should not be paid upfront
`aegis_deliver_work`	Submit completed work for on-chain validation
`aegis_check_job`	Check the current state of an escrow job
`aegis_settle_job`	Settle a job (confirm delivery or settle after window)
`aegis_open_dispute`	Initiate 3-tier dispute resolution
`aegis_claim_refund`	Claim refund on an expired job

Agent Discovery

Tool	Description
`aegis_lookup_agent`	Trust-check a provider's identity, owner, and ERC-8004 reputation before assigning paid work
`aegis_list_jobs`	List all escrow jobs for a specific agent

Utility

Tool	Description
`aegis_check_balance`	Verify USDC balance and escrow approval before funding a job; signer mode can inspect the connected wallet
`aegis_get_template`	Get a job template's default parameters
`aegis_should_i_escrow`	Advisory entry point that scores payment risk and returns the next AEGIS tools to use

Operating Modes

Read-only (default)

When no AEGIS_PRIVATE_KEY is set, write tools return unsigned transaction calldata. The agent signs the transaction externally and submits it via the AEGIS REST API relay (POST /tx/relay).

Signing mode

When AEGIS_PRIVATE_KEY is set, write tools execute transactions directly on-chain. Use this for trusted local setups.

Configuration

Variable	Description	Default
`AEGIS_CHAIN`	Target chain (`base-sepolia` or `base`)	`base-sepolia`
`AEGIS_RPC_URL`	RPC endpoint URL	Chain default
`AEGIS_RPC_URLS`	Comma-separated RPC failover list (ordered priority)	—
`AEGIS_PRIVATE_KEY`	Private key for signing (optional)	—
`AEGIS_API_URL`	REST API URL for relay (optional)	—
`AEGIS_USAGE_LOG_PATH`	Optional JSONL file path for per-tool usage logging	—
`AEGIS_USAGE_CONTEXT`	Usage label for clean attribution (`external`, `demo`, `test`, `ci`, `local`)	`local`
`AEGIS_USAGE_ACTOR`	Optional integrator/operator label written into usage records	—
`AEGIS_USAGE_SOURCE`	Optional framework/source label (for example `crewai`, `claude`, `custom-mcp`)	—

Usage Instrumentation

AEGIS can emit one JSONL record per tool call when AEGIS_USAGE_LOG_PATH is set. This is intended to separate real external usage from demos and tests without capturing full tool arguments.

Example setup:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@aegis-protocol/mcp-server"],
      "env": {
        "AEGIS_CHAIN": "base-sepolia",
        "AEGIS_USAGE_LOG_PATH": "/tmp/aegis-usage.jsonl",
        "AEGIS_USAGE_CONTEXT": "external",
        "AEGIS_USAGE_SOURCE": "crewai"
      }
    }
  }
}

Each record includes:

timestamp
session ID
tool name
tool category (read, advisory, write)
success/failure
latency
chain and mode
attribution fields (context, actor, source)

Reliability Notes

External RPC reliability is a known residual risk for live on-chain tests and operations.
For CI and production-like test runs, set AEGIS_RPC_URLS (or at least AEGIS_RPC_URL) to dedicated provider endpoints instead of relying on shared public RPC.
Resolution priority is: AEGIS_RPC_URL -> AEGIS_RPC_URLS entries -> chain-specific env (BASE_SEPOLIA_RPC_URL or BASE_RPC_URL/BASE_MAINNET_RPC_URL) -> chain default.
MCP E2E tests include bounded retries for transient transport failures (fetch failed, timeouts, temporary unreachable hosts) in tests/e2e/mcp-e2e.test.ts.
CI secreted E2E runs are manual-only (workflow_dispatch) and gated behind the protected testnet-e2e environment.
Canonical risk log and mitigation status live in docs/operations/ENGINEERING-RISK-TRACKER.md.
Operational preflight and incident procedure lives in docs/operations/RELIABILITY-RUNBOOK.md.

Registries

npm: @aegis-protocol/mcp-server
Smithery: aegis-protocol (namespace registered; hosted deployment pending paid plan)
MCP Registry: io.github.im-sham/aegis-protocol (live listing)

Development

# Install dependencies
pnpm install

# Build
pnpm build

# Run tests
pnpm test

# Development mode
pnpm dev

# Typecheck
pnpm typecheck

License

MIT

FilesExpand file tree

README.md

Latest commit

History