playbooks

home / mcp / aegis protocol mcp server

Aegis Protocol MCP Server

Provides a scalable MCP server enabling trustless escrow operations for AI agent transactions, including job creation, delivery, status checks, settlements, and disputes on Base L2.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "im-sham-aegis-protocol": {
      "command": "npx",
      "args": [
        "-y",
        "@aegis-protocol/mcp-server"
      ],
      "env": {
        "AEGIS_CHAIN": "base-sepolia",
        "AEGIS_API_URL": "https://relay.example.org",
        "AEGIS_RPC_URL": "https://polygon-rpc.example.org",
        "AEGIS_PRIVATE_KEY": "YOUR_PRIVATE_KEY"
      }
    }
  }
}

You can run the MCP server for the AEGIS Protocol directly from your development environment or integrate it with your AI agents to manage trustless escrow for agent-to-agent transactions. This server enables agents to create escrow jobs, deliver work, monitor status, settle payments, and initiate disputes on the Base L2 network.

How to use

You interact with the MCP server by configuring an MCP client to communicate through the provided command or via the local runtime. The server exposes actions that let you create trustless escrow jobs between AI agents, submit completed work for on-chain validation, check job status, settle deliveries, open disputes, and claim refunds for expired jobs. You can operate in read-only mode for unsigned transactions or in signing mode for direct on-chain transactions, depending on how you configure the client.

How to install

Prerequisites: ensure you have Node.js and npm installed on your machine. You will run the MCP server through a local runtime without a separate installation or you can integrate it with your client code.

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

With signing (local trusted setup)

If you want to enable signing by supplying a private key, add the private key to the environment for the MCP server configuration.

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

Operating modes

Read-only mode keeps the server in a view-only state where write actions emit unsigned transaction calldata. Your agent signs the transactions externally and submits them to the AEGIS REST API relay. Signing mode enables direct on-chain transactions when you provide a private key, suitable for trusted local setups.

Configuration

You can configure the following environment variables to tailor the MCP server to your network and relay setup.

Configuration variables

AEGIS_CHAIN: Target chain such as base-sepolia or base. Default is base-sepolia. Use this to select the network you operate on.

AEGIS_RPC_URL: RPC endpoint URL. Use the chain's default RPC endpoint if you do not provide this.

AEGIS_PRIVATE_KEY: Private key used for signing transactions in signing mode. This is optional for read-only mode.

AEGIS_API_URL: REST API URL for the relay. This is optional and used when you want to relay transactions through an API endpoint.

Registries

You can reference common registries to discover and verify MCP server implementations.

Development

If you are contributing or developing locally, use the standard workflow to install dependencies, build, test, and run in development mode.

Security notes

Keep private keys secure and avoid exposing sensitive environment variables in shared environments. Use read-only mode for testing or non-production workflows and enable signing mode only in trusted setups.

Troubleshooting

If you encounter issues starting the server, verify that your environment variables are set correctly, ensure Node.js and npm are installed, and confirm that the MCP server command is accessible in your PATH. Check logs for any error messages related to network access or signing configuration.

Key actions you can perform with the MCP server

Create a trustless escrow job between two AI agents with aegis_create_job. Deliver completed work for on-chain validation with aegis_deliver_work. Check the current status of an escrow job with aegis_check_job. Settle a job after delivery with aegis_settle_job. Open a three-tier dispute with aegis_open_dispute. Claim a refund for an expired job with aegis_claim_refund. Discover agent identities and reputations with aegis_lookup_agent. List all escrow jobs for a specific agent with aegis_list_jobs. Check USDC balance and escrow approvals with aegis_check_balance. Retrieve default parameters for a job template with aegis_get_template.

Available tools

aegis_create_job

Create a trustless escrow job between two AI agents.

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 after delivery or after the dispute window.

aegis_open_dispute

Initiate a three-tier dispute resolution.

aegis_claim_refund

Claim a refund on an expired job.

aegis_lookup_agent

Look up an agent's identity, wallet, and ERC-8004 reputation.

aegis_list_jobs

List all escrow jobs for a specific agent.

aegis_check_balance

Check USDC balance and escrow approval.

aegis_get_template

Get a job template's default parameters.