Use Ekubo Wallet with AI agents

Ekubo Wallet exposes a local Model Context Protocol (MCP) server to supported agents on the same computer. The agent receives a restricted wallet capability; owner-only capabilities remain in the native application. The local connection uses a versioned stdio bridge and same-user operating-system IPC. It has no HTTP listener, OAuth flow, bearer token, or client secret.

Follow the installation guide to configure a supported harness. Installing the fixed, credential-free connection entry is not an approval and grants no owner capability.

How a request works

1. The agent reads the wallet and enabled-network inventory instead of guessing an account or chain.
2. It reads balances, trusted token metadata, and the active signing policy as needed.
3. It obtains an exact execution plan from an appropriate producer. The wallet does not construct transfers, protocol actions, or calldata.
4. Ekubo Wallet simulates the exact calls against the configured network.
5. The active policy allows the transaction, denies it, or sends it to the owner for native review.
6. The agent waits until the request reaches a final result.

A simulation is not approval. If a request is waiting on the owner, review it in Ekubo Wallet’s Inbox. The agent should continue waiting rather than returning a request identifier and treating the task as finished.

If you ask to inspect one transaction that your policy would otherwise send automatically, the agent can submit it with must_review enabled. That adds native review to this submission only; it does not change policy, approve anything, or make a denied transaction sendable.

Typed-data and personal-message signatures always require native owner review. An agent cannot export a key, accept legal terms, approve its own request, or install a proposed policy.

An agent can also install an automation: bytecode the wallet polls on a schedule and whose returned calls take this same path. That is a way to suggest transactions without staying awake, not a way to gain authority — the policy still decides whether any of them send, and an automation whose calls the policy does not allow stops on its first tick.

A transaction allowed by policy can reach the wallet’s core signer without a native review. That gives the local server a narrow signing operation, not the key itself: the agent never receives raw key material or an owner-authentication capability. Read Security and privacy for the complete local boundary.

Signing policy belongs to the wallet account rather than to one agent connection. The same allow rule also applies to an equivalent transaction requested by an installed automation or a connected WalletConnect dapp. Read Signing policies before granting unattended authority.

Windows and Linux prompt-injection boundary

The statement above describes the MCP interface. On Windows and Linux, a prompt-injected harness that can execute shell commands or programs as the logged-in user can bypass MCP and query the current per-user credential backend directly for raw keys. Wallet policy and review cannot govern an external signer created from an extracted key. Read the credential-store limitation.

When a producer returns an artifact_reference, the agent must pass that JSON object to the wallet verbatim. It must not encode the object as a JSON string, rename fields, or reconstruct the execution plan. The wallet fetches the body itself and verifies the declared integrity and byte count.

The reference argument is an object, never quoted JSON text. Its execution-plan shape is:

{
  "kind": "artifact_reference",
  "artifact_type": "execution_plan",
  "url": "https://…",
  "integrity": {
    "algorithm": "keccak256",
    "value": "0x…"
  },
  "bytes": 1234
}

Those values are illustrative only. Copy the complete object returned by the producer; do not substitute placeholders or reuse an expired reference.

Local wallet and public Ekubo service

For harnesses whose configuration supports both local and remote MCP, agent setup installs two complementary entries:

• The local Ekubo Wallet entry reads wallet state, simulates, queues reviews, signs, submits, and reports results.
• The public Ekubo service at https://mcp.ekubo.org/mcp reads protocol data and prepares unsigned actions such as transfers, swaps, and liquidity operations. It receives no additional authority over the wallet.

The hosted service can temporarily store exact execution plans and other artifact bodies so the wallet can retrieve them by reference. Those plans can identify a sender and intended action. The local wallet independently retrieves, verifies, and simulates supported artifacts. It does not trust a friendly description in place of the exact calls it will display and potentially sign. Read Security and privacy for the service boundary.

Claude Desktop’s configuration file receives only the local entry. Add the public service separately as an account-level custom connector through Customize → Connectors.

The hosted service is not the only possible producer, and its protocol coverage changes without a wallet release. Supported protocols lists what it prepares today and states the contract a third-party MCP server satisfies to produce plans this wallet will execute.

Harness limitations

Supported harnesses include Codex, Claude Code, Claude Desktop, Gemini CLI, Cursor, OpenCode, and Grok Build. The ChatGPT desktop app can use the installed local MCP connection from its Work or Code tab; there is no ChatGPT wallet plugin.

Harness providers apply their own tool-use rules before a request reaches Ekubo Wallet. Some clients classify transaction submission as financial activity and refuse to call the wallet even though the wallet would require its own policy check or native review. Claude Desktop is a known example: use Code mode for the best chance of reaching wallet tools. If a harness still refuses, move the task to another supported harness. Changing harnesses does not weaken Ekubo Wallet’s local policy, simulation, or owner-review boundary.

Example requests

• “/loop Manage my USDC/USDG liquidity position on Ethereum. Claim fees, rebalance when the range drifts, and ask before every transaction.”
• “Claim all fees from my ve33 votes, sell balances worth more than their gas, and max stake the STONX proceeds.”
• “Compare moving half my ETH/USDC liquidity into USDC/USDG using current pool data. Show expected balances, gas, and range risk before preparing anything.”
• “Find every nonzero token approval from my company wallet, rank the risky spenders, and prepare revocations for the ones I choose.”
• “Propose a policy that only permits this recurring action, including exact constraints on its tuple arguments.”

Addresses, chain IDs, amounts, calldata, typed data, and message bytes are exact values. Check them in the native approval review rather than relying only on an agent’s summary.

Remove a connection

Open Settings and use the detected-agent controls to remove wallet-managed entries. This removes only the exact ekubo_wallet local entry and, where supported, the ekubo hosted companion entry. The wallet does not issue a persistent local bearer credential to revoke. Claude Desktop account connectors are managed in Claude’s Customize → Connectors screen.