Integration

MCP diagnostics

Register the published stdio server with Claude Code, Claude Desktop, Cursor, or another MCP-capable client. Running the command by itself normally prints nothing because it waits for the client; that is expected.

{
  "mcpServers": {
    "aegis": {
      "command": "npx",
      "args": ["-y", "@project-aegis/mcp-server"],
      "env": {
        "AEGIS_API_URL": "https://api.projectaegis.ai",
        "AEGIS_RUNTIME_API_KEY": "aegisrt_your-expiring-bound-runtime-key",
        "AEGIS_ROUTE_MODE": "bundler",
        "AEGIS_RPC_URL": "your-chain-rpc-url",
        "AEGIS_BUNDLER_URL": "your-erc4337-bundler-url"
      }
    }
  }
}

Prefer the values installed from the verified handoff over typing them into client configuration. Follow AEGIS_ROUTE_MODE: a direct handoff intentionally omits AEGIS_BUNDLER_URL, while a bundler handoff requires it. The public RPC can be replaced independently if it is rate-limited. MCP 0.5.0 forwards a scoped runtime key only to the exact Aegis-managed bundler route. The first check should be aegis_doctor. MCP exposes account context, holdings, permission state, preflight, receipt, error, and authenticated API tools, but it does not handle signing or submission.

Python execution

Install the released SDK for the helper layer. The calls-form action command follows the handoff route: direct mode probes capability and uses eth_call plus eth_estimateGas; bundler mode follows build, sign, UserOperation estimate, re-sign, then explicit submit. Neither route broadcasts without an explicit execute flag.

# Follows AEGIS_ROUTE_MODE and never broadcasts by default
aegis action run --env-file ./agent.runtime.env --request-file ./approved-action.json

# Re-run the identical approved request only after reviewing the dry run
aegis action run --env-file ./agent.runtime.env --request-file ./approved-action.json --execute

The SDK wraps calldata but does not encode a Uniswap, Aerodrome, or other DEX call. Construct target calldata from the exact protocol ABI for the target chain, then run target-level gas estimation and aegis_preflight_transaction before submission.

Python Integration

import os
from aegis_sdk import AegisClient, ActionCall, ActionRequest

client = AegisClient(os.environ["AEGIS_RUNTIME_API_KEY"])
request = ActionRequest(
    chain_id=CHAIN_ID,
    account=SMART_ACCOUNT,
    permission_id=PERMISSION_ID,
    calls=(ActionCall(target=TARGET, value=0, data=TARGET_CALLDATA),),
)
explanation = client.explain_action(request)

if explanation.policy_decision != "allowed":
    raise RuntimeError(f"Do not sign: {explanation.policy_decision}; correlation={explanation.correlation_id}")

# Policy allowance alone is not permission to submit. Continue with the SDK's
# separate dry-run, funding, signer, and selected-route checks, then require
# explicit execution.
print("Policy allowed; execution readiness:", explanation.execution_readiness)

JavaScript/TypeScript Integration

const API_URL = "https://api.projectaegis.ai";
const runtimeKey = process.env.AEGIS_RUNTIME_API_KEY;

async function explainAction(request: object) {
  const response = await fetch(`${API_URL}/api/v1/validate/explain`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-Key": runtimeKey!,
    },
    body: JSON.stringify(request),
  });
  if (!response.ok) throw new Error(`Explain failed: ${response.status}`);
  const result = await response.json();
  if (result.policyDecision !== "allowed") throw new Error(
    `Do not sign: ${result.policyDecision}; correlation=${result.correlationId}`
  );
  return result; // still run signer, funding, route, and exact dry-run checks
}

await explainAction({
  schemaVersion: "aegis.action-request.v1",
  chainId: CHAIN_ID,
  account: SMART_ACCOUNT,
  permissionId: PERMISSION_ID,
  calls: [{ target: TARGET, value: "0", data: TARGET_CALLDATA }],
});

Best Practices

• Generate a dedicated bot signer

  Never give your personal wallet key to a bot. Use “Generate Bot Signer” during agent creation to create a fresh keypair. The bot gets its own smart account with its own funds, completely isolated from your personal wallet.

• Explain the exact action before signing

  Send the real target, value, and calldata to the explanation path. Treat unknown as a stop, and keep policy allowance separate from signer, funding, route, target, and submission readiness.

• Use simulation for testing

  The /simulate endpoint lets you test without affecting usage quotas.

• Set up webhooks for alerts

  Configure webhooks to get notified of policy violations or permission expiry.

• Review audit logs regularly

  Monitor the audit log to track agent behavior and identify issues.

• All agents use Aegis Secure Accounts

  Every agent gets an Aegis Secure Account whose EntryPoint agent path is enforced on-chain. The owner remains a deliberate privileged recovery path, so keep the owner key out of the agent runtime.