@project-aegis/mcp-server

Aegis MCP Server

Dependency-free stdio MCP server for Aegis Smart Accounts.

It gives agents typed live account discovery, readiness diagnosis, permission/quota reads, error decoding, packaged deployment references, DeFi selector support, policy amount conversion, and optional authenticated Aegis API calls.

Run

From npm:

npx -y @project-aegis/mcp-server

From a local checkout:

node mcp/aegis/server.mjs

Pair the MCP server with the released Python SDK when the agent also needs the resumable setup CLI and UserOperation helpers:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install aegis-smart-accounts

Example MCP client config:

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@project-aegis/mcp-server"],
      "env": {
        "AEGIS_API_URL": "https://api.projectaegis.ai",
        "AEGIS_DASHBOARD_API_KEY": "optional-api-key",
        "AEGIS_RPC_URL": "optional-rpc-url"
      }
    }
  }
}

Local checkout config:

{
  "mcpServers": {
    "aegis": {
      "command": "node",
      "args": ["/absolute/path/to/aegis/mcp/aegis/server.mjs"],
      "env": {
        "AEGIS_API_URL": "https://api.projectaegis.ai",
        "AEGIS_DASHBOARD_API_KEY": "optional-api-key",
        "AEGIS_RPC_URL": "optional-rpc-url"
      }
    }
  }
}

Tools

• aegis_supported_chains
• aegis_get_contracts
• aegis_get_defi_support
• aegis_amount_to_base_units
• aegis_resolve_account_context
• aegis_doctor
• aegis_get_holdings
• aegis_get_permission_state
• aegis_decode_error
• aegis_get_userop_receipt
• aegis_preflight_transaction
• aegis_api_endpoints
• aegis_api_request

aegis_doctor, aegis_get_holdings, and aegis_api_request require AEGIS_DASHBOARD_API_KEY or AEGIS_API_KEY. Generic API requests only accept /api/v1/... paths.

aegis_resolve_account_context and aegis_get_permission_state follow the account's on-chain enforcer() to its registries. Context resolution also reports account.spendResolver() when the account exposes it and lists LP lifecycle selectors as a capability to prove with target-specific preflight. It does not assume the current deployment applies to an older account. The packagedReference returned by context resolution and aegis_get_contracts is explicitly non-authoritative for existing accounts; use resolved addresses for reads and the authenticated aegis_doctor for current-generation status.

aegis_get_holdings reports balances, while Doctor reports the selected permission's configured assets. A held token is not automatically spendable. Pass the intended token as Doctor's optional asset parameter and run transaction preflight before spending it.

aegis_get_userop_receipt reads eth_getUserOperationReceipt once and returns tx_hash from the nested receipt.transactionHash. A pending result has tx_hash: null; the top-level userOpHash is never substituted as a transaction hash.

aegis_decode_error accepts raw revert data as revert_data (with revertData and data compatibility aliases) and classifies the stable Aegis selectors 0x17bb5f11, 0x2a4c6ff6, and 0xacfdb444. It can also extract a selector from the supplied error message.

aegis_preflight_transaction requires a chain RPC URL via AEGIS_RPC_URL or the tool's rpc_url argument. It calls the live PermissionEnforcer.checkAction(agentId, permissionId, actionHash, actionData) path and checks EntryPoint deposit/native ETH prefund readiness for a supplied UserOperation gas envelope. It does not submit a UserOperation and does not replace bundler simulation. Do not pass an unsigned or empty-signature operation to simulateValidation: validation can fail before prefund payment and produce a misleading AA21.

The DeFi support response includes target-ABI warnings. Resolver recognition is a policy check, not proof that a target contract implements the selector. In particular, PancakeSwap V3 NFPM on Base Sepolia (0x46A15B0b27311cedF172AB29E4f4766fbE7F4364) requires tuple decreaseLiquidity((uint256,uint128,uint256,uint256,uint256)) (0x0c49ccbe); the Aerodrome/Slipstream flat selector (0x03a3f2ab) can be recognized by Aegis but revert with empty data at PancakeSwap. Run target eth_estimateGas/eth_call with the exact verified ABI in addition to Aegis preflight.

The built-in LP lifecycle support includes both Uniswap V3 tuple and Aerodrome/Slipstream non-tuple unwind selectors: decrease liquidity, both collect ABI shapes, and burn(uint256). Always run aegis_get_defi_support and aegis_preflight_transaction against the account's actual position-manager target before submitting; an older account may point at an older immutable resolver and must be migrated rather than assuming current-generation support.

Smoke Test

cd mcp/aegis
npm run smoke