@project-aegis/mcp-server

Aegis MCP Server

Dependency-free stdio MCP server for Aegis Smart Accounts.

The capability-gated exact preflight documented here requires MCP server 0.3.0 or newer. Verify the registry with npm view @project-aegis/mcp-server version; before 0.3.0 is published, run the repository checkout for implementation testing.

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. It does not hold the bot signing key and it does not sign or submit a UserOperation; use the Python SDK and the Aegis smart-account skill for execution.

For the human/operator sequence, see docs/AGENT_SMART_ACCOUNT_QUICKSTART.md.

Run

From npm:

npx -y @project-aegis/mcp-server

This is a long-running stdio server. Running the command by itself normally prints nothing and does not return to the shell because it is waiting for an MCP client to speak JSON-RPC. That is expected. Register it with Claude Code, Claude Desktop, Cursor, or another MCP-capable client instead.

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. The MCP configuration contains only MCP settings; the agent's signer key and smart-account runtime variables belong in the separate secure agent environment described by the Aegis Quick Start.

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@project-aegis/mcp-server"],
      "env": {
        "AEGIS_API_URL": "https://api.projectaegis.ai",
        "AEGIS_RPC_URL": "${AEGIS_RPC_URL}",
        "AEGIS_BUNDLER_URL": "${AEGIS_BUNDLER_URL}"
      }
    }
  }
}

For Claude Code, the equivalent shortcut is:

claude mcp add aegis -- npx -y @project-aegis/mcp-server

The exact settings-file location is client-specific. Use the same mcpServers.aegis JSON shape in Claude Desktop, Cursor, or another client.

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_RPC_URL": "${AEGIS_RPC_URL}",
        "AEGIS_BUNDLER_URL": "${AEGIS_BUNDLER_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 need backend authentication. In an agent runtime, use only an expiring, agent/account/chain-bound AEGIS_RUNTIME_API_KEY with the required read or audit scope. Issued runtime keys use the aegisrt_ prefix; the MCP server rejects a management-format key placed in that variable, so renaming an old key cannot make it least privilege. Wallet-scoped AEGIS_API_KEY / AEGIS_DASHBOARD_API_KEY credentials belong only in a trusted control-plane provisioning process and are omitted from the default MCP configuration. Generic API requests accept only /api/v1/... paths, and the backend still enforces the credential's route, scope, and bindings. The server has no direct UserOperation signing or submission tool.

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_RPC_URL is for chain reads and ordinary EVM RPC. AEGIS_BUNDLER_URL is the explicit ERC-4337 endpoint used for UserOperation receipts (and by callers for eth_estimateUserOperationGas / eth_sendUserOperation). Some providers use one URL for both roles, but it must still be configured explicitly as the bundler; a blank value is not self-submit. aegis_preflight_transaction pins one observation block, verifies the live EntryPoint/enforcer/resolver bytecode tuple, resolves the full target calldata through the account-bound resolver, and compares read-only validation with sequential execution semantics. It emits an exact allowed or denied verdict only for a capability tuple whose generated explanationSupported state has been promoted; an unproven tuple returns unknown/POLICY_NOT_CHECKED even when its hashes match. Policy allowance still does not prove signer, route, or target readiness, and the tool never submits. Do not pass an unsigned or empty-signature operation to simulateValidation: validation can fail before prefund payment and produce a misleading AA21.

AEGIS_EXACT_EXPLANATION_ENABLED=true is an operator rollout switch, not a user setup variable. It has no effect unless the exact tuple also carries reviewed passing conformance evidence in the generated registry. Leave it unset during shadow evaluation; setting it back to false is the global rollback. The parity harness uses a test-namespaced override that also requires NODE_ENV=test; it is not a deployment control and must never be copied into a user runtime. Production exact verdicts always require both promotion evidence and the operator rollout switch.

Intent API status

The /api/v1/intents endpoints and IntentRegistry contracts are experimental. They have not been validated end to end and are not part of the normal onboarding path. New accounts use MODE_POLICY_ONLY; do not use intent envelopes or the intent endpoints for production execution until Aegis explicitly marks them supported.

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.

Robinhood Chain Testnet (46630) is exposed as a deployed v15 network profile so agents can identify the chain without inventing configuration. The contracts are deployed and verified, but the Aegis API is not yet enabled for this chain; do not target Robinhood from the dashboard/API until the rollout gate is closed. Its public RPC is not a bundler, and the packaged Alchemy endpoint is the submission route when the chain is enabled.

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