MCP tools

The agensai MCP server exposes 10 tools. 5 are reads (no signing); 5 are writes (orchestrator or agent signs). Inputs are validated by Zod schemas before any signing happens. Tool descriptions are deliberately authoritative, they tell the LLM whether to retry on failure and how to reason about each operation.

This page mirrors the canonical schemas in apps/mcp/src/mcp/schemas.ts. When that file changes, this page should change with it.

list_agents

List the AI agents owned by this orchestrator. Read-only. Returns ENS, smart-account address, chain id, status (active / expired / revoked), expiry timestamp, and permissionId for each agent.

• "Show my agents."
• "Which agents are still active?"
• "List the agents that have expired."

get_agent

Get a full snapshot of one agent by ENS. Read-only.

Returns saAddress, owner, chainId, expiry, status, permissionId, and the agent's permission bundle.

Returns AGENT_NOT_FOUND if the ENS doesn't resolve to an agent on the configured chain.

• "Show me everything about dca-bot."
• "What are alice's permissions?"

create_agent

Create a new permission-bound agent. Issues an ENS subname, deploys an ERC-4337 smart account, grants an ERC-7715 permission with the supplied permissions. Permissions are enforced on-chain by the smart account; calls that exceed them will revert.

Do not retry on PERMISSION_VIOLATION or NAME_TAKEN, adjust the input first.

• "Create dca-bot with 50 USDC/week on Uniswap, 30 days."
• "Spawn alice as a research agent, no spend, expires in 7 days."
• "Spin up a service-payer with $9.99/month USDC, whitelist anthropic.eth and openai.eth."

transfer

Send tokens from a named agent to a recipient. The agent's ERC-7715 spend, contract, and rate permissions are enforced on-chain, calls that exceed them revert. Returns the real on-chain txHash, not just the bundle callId.

Do not retry on PERMISSION_VIOLATION; the cap is real.

• "Send 5 USDC from dca-bot to alice."
• "Transfer 0.01 ETH from service-payer to 0x..."

execute

Run a read-only EIP-1193 JSON-RPC method scoped to the agent's chain. Allowlist: eth_call, eth_getBalance, eth_blockNumber, eth_getCode, eth_getStorageAt, eth_getLogs. Anything else is rejected as INVALID_INPUT.

Read-only. This tool cannot send transactions.

• "What's dca-bot's USDC balance on Base?" → eth_call against USDC balanceOf.
• "Get the current block on Base." → eth_blockNumber.

revoke

Revoke an agent's on-chain ERC-7715 permission. After this, the agent can no longer sign transactions. The ENS subname survives.

Destructive: do not retry blindly; the agent is unusable after success.

Status note: the on-chain revoke is fully enforced. The agent's status ENS text record is not flipped to "revoked" today; it stays "active". Trust the on-chain permission, not the text record. Status-text-record flip lands in a follow-up release.

The ENS can be re-granted via create_agent under a different name, or extended via permission_add (which is implemented as revoke + re-grant under the hood; see below).

• "Revoke dca-bot."
• "Kill alice."

read_contract

Encode and call a single read-only contract method via the JSON-RPC eth_call path. Takes a Solidity-style ABI fragment, decodes the result, returns both raw and decoded values.

Read-only.

• "What's the USDC balance of alice on Base?"
• "Read totalSupply on 0x... on Optimism."

resolve

Resolve an ENS name to its on-chain address.

Returns the address that should be used for that name on the requested chain. The lib chooses the chain-appropriate resolver slot transparently.

Returns RESOLUTION_FAILED if no record exists for that chain.

• "What's alice's address on Base?"
• "Resolve uniswap.eth on chain 1."

fund_agent

Top up an agent's wallet from the orchestrator. Orchestrator's owner key signs directly, so this moves any amount of USDC or ETH regardless of the agent's spend cap.

• "Top up dca-bot with 10 USDC."
• "Fund alice with 0.01 ETH for gas."

drain_agent

Sweep an agent's balance back to the orchestrator. For v0.5.x+ agents, the orchestrator signs a cross-SA execute as co-owner. For legacy agents, the agent's local key initiates. Leaves a small reserve for gas by default.

drain_agent does not revoke the permission; only moves the agent's own balance. Pair it with revoke when retiring an agent.

• "Send all funds from dca-bot back to orc."
• "Sweep alice and revoke it."

Changing an agent's scope

Permissions are immutable per ERC-7715. To change what an agent can do: revoke it, drain it, and create_agent with the new bundle. The ENS subname is preserved on chain so audit history survives; the new permission gets a fresh permissionId.

Effective prompting

Three rules cover most agent-driven work:

1. Use ENS names everywhere. Tools accept hex addresses where useful, but ENS is the human surface. Saying "send 5 USDC from dca-bot to alice" is unambiguous; using hex addresses introduces error.
2. Be specific about scope at create time. "50 USDC per day on Uniswap, 30 days" is enough for the LLM to construct a clean permission bundle. Vague prompts produce vague permissions.
3. Trust the on-chain bound. If you ask for something that would violate a grant, the validator reverts. You don't need defensive prompting; the chain enforces.

Error envelope

Every tool returns a structured error on failure:

{
  "code": "PERMISSION_VIOLATION",
  "message": "spend cap exceeded",
  "details": { "permissionId": "0x...", "attempted": "60", "cap": "50" }
}

Common codes:

See JAW error handling for the underlying RPC error shapes.