Skip to Content

Agent Mode (MCP)

Agent Mode is how an AI agent works with your KeepKey. The goal is a wallet flow driven end to end: find and open the site, drive the dApp’s interface, decode what the dApp is actually asking for, explain it in plain terms, and walk you through the review. You sign on the device. The agent does the work and the explaining; you and the KeepKey remain the signing authority.

MCP (Model Context Protocol) is a standard protocol in which a server publishes a catalog of callable tools that clients discover with tools/list and invoke with tools/call. KeepKey publishes its tools over MCP, so an agent needs no custom transport to reach them. MCP standardizes the plumbing, not the setup: you still need the KeepKey Desktop running, a pairing key for the agent to present, and Agent Mode switched on. Being able to speak MCP does not by itself grant an agent access to your wallet.

Browser use video course

Watch Browser use with BEX: seven short lessons using Codex as the example agent.

  1. Connect Codex to your browser · 2:30
  2. Your first browser task · 1:29
  3. Work in the right profile · 1:34
  4. Complete a browser workflow · 1:31
  5. Understand a wallet request · 1:36
  6. Troubleshoot and disconnect · 1:52
  7. A professional DeFi workflow · 2:33

The course covers setup, profile selection, a complete browser task, request review, troubleshooting, and professional DeFi analysis and documentation.

Availability

Use the current KeepKey Desktop  and browser extension . Tool availability depends on both builds and the connected extension. Inspect the live tools/list catalog rather than assuming every installed version has the same tools. If BEX Settings has no Agent Mode (MCP) section, update the extension before continuing.

The device is the gate

An agent can navigate, click, type, read state, and explain. It can assemble a transaction and drive the extension’s side of an approval right up to the moment of signing. What it cannot do is press the button on your KeepKey. Signing requires confirmation on the device itself, and no MCP tool can perform that press.

Browser-driving tools can change websites. The physical confirmation applies to KeepKey signing; it does not gate browser actions such as posting or changing account settings.

Two honest qualifications. The confirmation is per transaction, not per signature: a multi-input Bitcoin transaction produces several signatures from one confirmation. And the button proves that a human approved; it does not vouch for what the agent composed. Read the device screen rather than treating the press as a formality — particularly for payloads the device cannot render meaningfully, such as raw-byte message signing.

Why the tools live in the extension

A browser-automation tool that launches its own throwaway profile has no extension in that profile, so it cannot exercise a dApp as a wallet user. That is a fact about the profile, not about your machine: KeepKey Desktop runs as a separate process and keeps its pairings in an on-disk database, and the KeepKey is a USB device attached to the host. Both are there regardless of which browser is running.

Pointed at your real Chrome, a general-purpose tool with JavaScript access can already read what any page can read — the extension injects its provider into every page, so eth_accounts and eth_chainId are available to page script without any bridge. What it cannot reach is the extension’s own internal state: the approval queue, the provider-call log, the connected-origins registry, and the bridge and service-worker internals. Those live in the background service worker’s memory, and they are what the bex_* tools add.

There is also a hard constraint. Playwright and Puppeteer cannot run inside the extension at all: the background bundles to a single IIFE with no Node builtins. Driving the browser from within the extension is the only way to put the driving and the wallet-side observation in one process.

What works today

The extension publishes its tool catalog and KeepKey Desktop forwards it to the client. Profile-aware Desktop builds additionally provide bex_browsers and a browser argument on the forwarded tools. The live tools/list response is the source of truth for your build. The reference below covers these extension tool groups:

  • Introspection (6): bex_status, bex_accounts, bex_pending_requests, bex_connected_sites, bex_logs, bex_ext_console. These report device, account and session state.
  • Browser driving (11): bex_tabs, bex_navigate, bex_snapshot, bex_find, bex_click, bex_type, bex_select, bex_read_page, bex_screenshot, bex_bring_to_front, bex_panel.
  • Page debugging (4): bex_console, bex_network, bex_perf, bex_storage.

Agent Mode is off by default, and the agent endpoints accept only local, non-browser callers.

Setup

Agent Mode connects an MCP-speaking agent — Claude Code, Claude Desktop, or any other MCP client — to your wallet over localhost. Connecting an agent does not hand it signing power.

Prerequisites

  • KeepKey Desktop running, with its local server on http://localhost:1646. KeepKey Desktop hosts the MCP endpoint, not the extension — a Chrome MV3 extension cannot listen on a port. The extension connects outbound to KeepKey Desktop over a WebSocket.
  • The extension paired with KeepKey Desktop. The existing pairing key is the bearer token your agent presents. There is no separate MCP key and no separate MCP pairing flow.

Steps

Watch: Connect Codex to your browser.

There are two separate controls. API Bridge is in KeepKey Desktop Settings and enables local application connections. Enable MCP is in the BEX extension’s own Settings and connects that browser profile to the agent bridge. Turning on the Desktop control does not turn on the BEX control.

  1. Open the extension side panel and go to Settings → Agent Mode (MCP).
  2. Turn on Enable MCP. It is off by default. While it is off, the extension opens no socket.
  3. Press Copy agent config. This copies a ready-to-run claude mcp add command with your pairing key already embedded. If the extension is not paired yet, the button tells you so instead of copying.
  4. Choose your client below. The copied command is for Claude Code; Codex uses the same key through an environment variable.
Actual BEX Settings showing Agent Mode (MCP), Enable MCP switched on and Copy agent config directly below it
These controls are inside the BEX side panel. The captured build’s description says tools only read; browser-driving tools can also change websites.

Connect Codex CLI

Copy agent config currently copies a Claude command. For Codex, use the same local pairing key through an environment variable. In a private local editor, identify the value after Authorization: Bearer and before the closing quote; that value is the key. Do not paste the whole copied command as the key, and do not share it with the agent in chat. This is a KeepKey pairing key, not an OpenAI API key.

In a local Bash or Zsh terminal, run this command by itself:

read -s KEEPKEY_API_KEY

Paste only the key at its hidden input and press Enter. After that command finishes, run:

export KEEPKEY_API_KEY codex mcp add keepkey --url http://localhost:1646/mcp --bearer-token-env-var KEEPKEY_API_KEY codex mcp list codex

Start Codex from that terminal so it inherits the variable. The saved configuration refers to the environment variable’s name; a future terminal must supply its value again. Do not print the variable to check it. See the official Codex MCP configuration documentation  for client options.

The equivalent entry in Codex’s config.toml is:

[mcp_servers.keepkey] url = "http://localhost:1646/mcp" bearer_token_env_var = "KEEPKEY_API_KEY"

If a keepkey server entry already exists, inspect and update that entry rather than creating a second connection with a different key. After changing configuration, start a new client session and verify the live tools below. Registration or mcp list alone does not establish a working BEX connection.

Connect Claude Code or another client

The copied command has this shape, with <KEY> replaced by your real pairing key:

claude mcp add --transport http keepkey http://localhost:1646/mcp --header "Authorization: Bearer <KEY>"

For other MCP clients (.mcp.json, Claude Desktop), configure it manually:

{ "mcpServers": { "keepkey": { "type": "http", "url": "http://localhost:1646/mcp", "headers": { "Authorization": "Bearer YOUR_PAIRING_KEY" } } } }

The copied string contains your pairing key. Treat it like a password: paste it only into your own agent, and never into a chat, an issue, or a screenshot.

Verify it works

On a profile-aware build, ask for bex_browsers, identify the intended profile from its tabs, then call bex_status with that browser identifier. A ready hardware-wallet connection reports:

  • deviceConnected: true — your KeepKey is plugged in and responding
  • vaultPaired: true — the extension holds a pairing key
  • walletInitialized: true — the wallet is loaded and ready to answer account queries
  • bridge: "up" — the extension’s outbound WebSocket to KeepKey Desktop is live

bex_status answers even when the bridge is down, so it is the right first call when something looks wrong. If it reports bridge: "down", Enable MCP is off or the extension has not reconnected yet — reconnect backoff runs from 5 seconds up to 60 seconds. If vaultPaired is false, re-pair the extension with KeepKey Desktop and copy the config again, since the key will have changed.

Next, try the first browser task. For multiple Chrome profiles, follow Choose the right profile before reading wallet state or acting on a page.

Browser and tab routing

bex_browsers lists connected BEX profiles. On builds supporting profile routing, pass its selected identifier as browser to every tool for that profile. Use bex_tabs to get the tab’s tabId; a tab identifier does not replace the browser identifier.

Omitting browser with multiple connected profiles returns browser_ambiguous. A stale identifier returns unknown_browser. List browsers and tabs again after a reconnect or Desktop restart. Do not choose a profile by connection order or assume its signed-in website account matches the account in another profile.

Introspection tools

These six tools read state and observe traffic, and none of them can sign.

Transport and authentication

The MCP endpoint lives in KeepKey Desktop, not in the extension. Agents speak Streamable HTTP to POST http://localhost:1646/mcp. The server identifies itself with serverInfo.name set to keepkey-vault.

There is no MCP session. Each POST is an independent JSON-RPC request, authenticated on its own. Clients conventionally send initialize first to negotiate a protocol version, but it establishes no state and is not what grants access — tools/list and tools/call are answered without it. The server’s own protocol version is 2025-06-18, and it accepts 2025-06-18, 2025-03-26, and 2024-11-05, echoing back the version you request when it is one of those and otherwise answering with its own.

POST /mcp requires an Authorization: Bearer <pairing key> header, using the existing KeepKey Desktop pairing key. A request with no token or a bad one returns 401. Two checks run before authentication: a non-loopback caller is rejected with 403 loopback only, and any request carrying an Origin or Sec-Fetch-Site header is rejected with 403 /mcp is not reachable from a browser. That second check excludes all browsers, including same-origin and loopback ones, because KeepKey Desktop serves browser content at its own localhost origin — so a localhost-origin allowlist would not be a boundary. Browsers cannot strip either header; non-browser agents send neither.

The tools

ToolWhat it returnsArguments
bex_statusbridge, extension version, keepkeyState and keepkeyStateName, deviceConnected, vaultPaired, walletInitialized, activeEvmNetwork (chainId, networkId, name) or null, swStartedAt, bridgeConnectedAtnone
bex_accountsPer-chain request_accounts result in the raw shape a dApp receives, plus pubkeys. A chain that fails returns an error field instead of blocking the otherschains (optional array; defaults to ethereum, bitcoin, bitcoincash, dogecoin, litecoin, dash, thorchain, mayachain, cosmos, osmosis, ripple)
bex_pending_requestsThe live approval queue: key, dApp-supplied id, method, params, origin, chain, requestedAtnone
bex_connected_sitesOrigins that have made provider requests, with chains touched and firstSeen / lastSeennone
bex_logsRing buffer of provider requests and responses (ts, origin, chain, method, params, result or errorCode / errorMessage, durationMs)pattern, since, limit (all optional)
bex_ext_consoleThe extension background’s own console output, for debugging the extension itself. Wiped when the service worker restartslevel, pattern, since, limit (all optional)

What they are good for

bex_pending_requests is the decode-and-review step. When a dApp asks you to approve something, the exact method and parameters land in this queue, and the agent can read them and explain what the site is actually requesting before you look at the device. Address entries by key, not id — id is dApp-supplied and two tabs commonly collide on the same value.

bex_logs exposes provider traffic for debugging a stuck connection: filter by pattern (a case-insensitive regex matched against method, origin, chain, and error message), by since (epoch milliseconds), or cap with limit (default 100). The buffer holds the most recent 500 entries and long results are clipped.

bex_accounts is not an inert read. It routes through the same path page traffic takes, so calling it can trigger wallet initialization. The default chain list is limited to chains whose request_accounts is a cache read, so it does not require a device round-trip.

All of these registries are in-memory and are wiped when the MV3 service worker restarts. Compare swStartedAt across calls to detect a wipe.

Browser-driving tools

Confirm that your live tools/list response includes the browser-driving tools before following these procedures. Older builds can expose only fallback introspection tools.

Introspection tells an agent what the wallet sees. Browser driving is what lets it do the rest of the job: open the site, drive the dApp UI, and walk you through what the dApp is asking for.

The tools

ToolArgumentsWhat it does
bex_tabsaction (list | create | close | select | new-window), tabId?, url?List, open, close or focus tabs, or open a new window. Defaults to list.
bex_navigateurl, tabId?Navigate a tab and wait for load.
bex_snapshottabId?Accessibility snapshot of interactive elements, each with a [ref=eN] handle.
bex_findtext, regex?, tabId?Search the snapshot by accessible name; returns only hits and their refs.
bex_clickref, element, tabId?Click an element by ref.
bex_typeref, element, text, submit?, tabId?Type into a field, replacing its value. submit presses Enter.
bex_selectref, element, value, tabId?Choose an option in a select.
bex_read_pageselector?, maxChars?, tabId?Rendered text, defaulting to main then body.
bex_screenshottabId?, quality?JPEG of the visible viewport, quality clamped to 1-100, default 60. Focuses the tab first, since Chrome can only capture a window’s active tab.
bex_bring_to_fronttabId?Raise the browser window so the user can watch. Call it when a browser task starts.
bex_panelaction (show | hide | status), message?, level? (info | action-needed | done), tabId?Control the in-page status panel. Use level: action-needed right before a step that needs a KeepKey button press.

element on the acting tools is a human-readable description of the target, recorded in the audit trail.

Pass the intended browser and tabId. Without an explicit tab, a tool can act on the user’s active tab. Get browser identifiers from bex_browsers and tab identifiers from bex_tabs. See the worked browser workflow.

Page-debugging tools

These read what a dApp is doing, for finding out why it is broken. They capture from the moment the extension injected into the page onward.

ToolArgumentsWhat it returns
bex_consolelevel?, pattern?, since?, limit?, tabId?The page’s console output plus uncaught errors and unhandled rejections.
bex_networkstatus? (error for failures only), pattern?, since?, limit?, tabId?fetch and XHR requests: method, URL, status, duration, failures. No bodies or headers; misses workers and cross-origin iframes.
bex_perftabId?Core Web Vitals, JS heap and DOM size, a short FPS sample and long-task totals.
bex_storagetabId?localStorage, sessionStorage, cookie names, IndexedDB and Cache Storage names for the page’s origin. Read-only; HttpOnly cookies are invisible.

The ref model

The agent never writes a CSS selector and never clicks a coordinate. bex_snapshot returns an accessibility-shaped listing where every interactive element carries an opaque handle, and the agent acts on those handles:

page https://app.example.com/swap — "Swap" - heading "Swap" [level=1] - button "Connect Wallet" [ref=e1] - textbox "You pay" [ref=e2] value="0" - button "Swap" [ref=e3] [disabled]

bex_click with ref: "e1" clicks Connect Wallet. Refs are re-minted on every snapshot, so re-snapshot after anything that changes the page; a stale ref is rejected rather than guessed at. This is the convention Microsoft (Playwright MCP) and Google (Chrome DevTools MCP) arrived at independently.

Screenshots are for visual verification only. You cannot act on one — there are no refs in a JPEG, and no coordinate clicking. Use bex_snapshot to find things.

Making it work on real dApps

Wallet UIs break naive automation, so the design accounts for how they are actually built. Open shadow roots are pierced, because web3modal and other Lit-based connect modals live inside them (closed roots remain invisible). Clicks dispatch a full pointer sequence rather than a bare click, because Radix and Headless UI listen on pointerdown. Typing goes through the prototype’s native value setter, which defeats React’s value tracker — a direct value assignment is a no-op to React. Disabled elements refuse clicks, since “the Swap button is disabled until you enter an amount” is exactly the gating an agent run should surface rather than bypass.

This costs no new Chrome permissions (<all_urls> and tabs are already granted) and no new dependencies. It does not use chrome.debugger, so there is no “extension is debugging this browser” infobar.

The KeepKey Desktop side

KeepKey Desktop’s /mcp endpoint used to hardcode its tool catalog and wrap every tool result as a text block, which kept these tools inert: tools/list never advertised them, tools/call rejected them at a tool-name guard, and bex_screenshot had nowhere to put a JPEG — MCP carries images as image content blocks with data and mimeType.

Browser-capable builds proxy the extension catalog and preserve content blocks, including images. Profile routing is a separate Desktop capability: Desktop supplies bex_browsers and handles the browser argument before forwarding a call. Check the live catalog when either app changes.

Security: the signing boundary

Signing requires confirmation on the KeepKey itself. An agent can read state, explain what a dApp is asking for, and click through the dApp on your behalf. It can carry a transaction all the way to the point of signing. It cannot press the button.

The safety promise is the device confirmation, not “the tools are read-only” — with browser driving, they are not.

One scope note: this guarantee is about physical KeepKey hardware. KeepKey Desktop also supports an opt-in, user-installed emulator that runs firmware as a local library and confirms with an on-screen click instead of a button press. Emulator signing carries no hardware guarantee and should not be treated as equivalent to device signing.

Off by default

Agent Mode is stored under keepkey-agent-mode and defaults to off. While it is off, the extension opens no socket and exposes nothing. The toggle is the real data gate, not the tool list.

To turn it off, open the side panel, go to Settings → Agent Mode (MCP), and switch off Enable MCP. The extension closes its WebSocket immediately.

With the bridge down, bex_accounts, bex_pending_requests, bex_connected_sites and bex_logs return an error result carrying bridge_disconnected. bex_status is deliberately exempt and returns a normal result reporting bridge: "down", so an agent can always get a truthful liveness answer.

How /mcp is guarded

The MCP endpoint lives in KeepKey Desktop at http://localhost:1646/mcp and applies three independent checks, in this order:

  • Loopback only. A non-loopback caller is rejected with 403 before anything else.
  • No browsers. A request carrying an Origin or Sec-Fetch-Site header is rejected with 403, including same-origin and loopback ones.
  • Bearer token. POST requires a valid pairing key, or returns 401.

The agent endpoints are protected by these explicit per-route checks rather than by the socket binding: the KeepKey Desktop process itself listens on all interfaces, so other endpoints such as /api/health are reachable from your local network. The bridge itself is outbound to loopback, and the introspection tools make no outbound internet calls. With browser driving, an agent can navigate your browser to arbitrary internet sites — that traffic is your browser’s, not the bridge’s.

The pairing key is a secret

The token is your existing KeepKey Desktop pairing key, not a separate MCP credential. Copy agent config embeds it in the command it copies. It is loopback scoped, so it is not usable from another machine, but treat it like any other secret: paste it into your own agent, never share it, never commit it. To rotate it, re-pair the extension with KeepKey Desktop.

What an agent can see when enabled

With Agent Mode on, an agent can read your addresses and accounts across chains, your device status, the approvals a dApp is currently waiting on, the sites you have connected, and your provider traffic logs. That is privacy relevant. It is a view of your wallet’s activity, handed to whatever agent holds the key.

What browser driving means

With the browser-driving tools, an agent acts in your browser as you: it opens tabs, fills forms, clicks through a dApp. That is real power, and it is worth stating plainly rather than reassuring you.

Be clear about what the device button does and does not cover. It gates signing on the KeepKey. It does not gate anything else an agent can reach in a browser where you are already logged in — an exchange withdrawal, a hot wallet, an email password reset. Those paths never touch the device. The button is the guarantee for your KeepKey-held funds; it is not a general guarantee about everything an agent does in your Chrome. Enable browser driving with that in mind, and only for agents you would trust with a logged-in browser session.

Troubleshooting

Start by identifying the layer that failed: client configuration, Desktop authentication, BEX connection, browser/profile routing or the page itself. Do not re-pair or reset data before reading the error.

SymptomFirst check
Codex registered the server but cannot authenticateLaunch it from the terminal that exports KEEPKEY_API_KEY; a saved variable name is not a saved token value.
No connected browsers or bridge_disconnectedBEX Settings → Enable MCP, the intended Chrome profile, Desktop running and extension pairing.
browser_ambiguous or unknown_browserRediscover with bex_browsers, inspect tabs and pass the selected browser.
A stale element ref or unexpected pageConfirm browser, tabId and URL, then take a fresh snapshot before acting.
Clicked Save but no verified resultRead the validation message and persisted state; do not report success from the click alone.

Almost every failure is one of two things: a missing or stale bearer token, or Agent Mode being off in the extension.

401 {"error":"No bearer token — pair first via POST /auth/pair"}

The request reached KeepKey Desktop with no Authorization header. /mcp has no anonymous mode. Re-add the server with the header, and check that your MCP client actually forwards headers from its config.

401 with a key supplied

The body reads {"error":"Invalid or expired API key — re-pair via POST /auth/pair"}. The key is not a currently valid KeepKey Desktop pairing key — usually a config copied before the extension re-paired. Re-pair the extension with KeepKey Desktop, then use Settings → Agent Mode (MCP) → Copy agent config to get the live key and update your MCP config. That config contains a secret; do not commit it.

403 {"error":"/mcp is not reachable from a browser"}

The request carried an Origin or Sec-Fetch-Site header. /mcp refuses all browser callers, even with a valid key and even from localhost. Call it from a local process — your agent CLI — not from a web page or a devtools console.

403 {"error":"loopback only"}

The request came from another machine. The agent endpoints accept loopback callers only. Run your agent on the same computer as KeepKey Desktop.

Connection refused on port 1646

KeepKey Desktop is not running. Start it and retry. The MCP endpoint is served by KeepKey Desktop, not by the extension.

Tools answer bridge_disconnected

The message is KeepKey extension is not connected to the vault bridge (is the BEX running with Agent mode enabled?). KeepKey Desktop is up, but nothing is on the extension end of the bridge. Check, in order: Enable MCP is on in side-panel Settings (it defaults to off), Chrome is running with the extension loaded, and the extension is paired with KeepKey Desktop. bex_status still answers while the bridge is down, reporting bridge: "down" — use it to confirm. Note the JSON field is error, not code, and the same value appears if the extension is not installed, not yet paired, or its service worker has been evicted.

bex_accounts comes back empty or full of errors

The wallet is not initialized: device unplugged or locked, or KeepKey Desktop is not paired. Per-chain entries return as {chain, error} with Wallet not initialized. Plug in and unlock the device, open the side panel so initialization runs, then retry.

bex_click, bex_navigate and friends are not listed, or are rejected

Your KeepKey Desktop version is older than 1.5.0, the first release that serves the extension’s tool catalog. Older versions advertise the five introspection tools only and return JSON-RPC error -32602 unknown tool: bex_click for anything else. Update KeepKey Desktop. If the browser tools are listed but calls fail, that is a different problem — start with bex_status and the bridge checks above.

POST /mcp drops the socket instead of returning a status

Seen as fetch failed or UND_ERR_SOCKET. Older KeepKey Desktop builds could fail to render the 401 for /mcp. The underlying cause is still one of the two 401s above — check your Authorization header first, then update KeepKey Desktop.

Disconnect and verify

Watch: Troubleshoot and disconnect.

  1. Finish or reject outstanding requests and record their actual result.
  2. In the intended BEX side panel, open Settings → Agent Mode (MCP) and turn Enable MCP off.
  3. Ask for the browser list again. That profile should no longer be connected. If no profiles remain, bex_status can report bridge: "down"; a read that needs the extension returns bridge_disconnected. If other profiles remain, their bridge may still be up.
  4. If reconnecting later, switch MCP on, rediscover browser/tab identifiers and verify state before continuing.

Disabling MCP stops that profile’s agent bridge. Revoking the extension’s pairing in Desktop Settings revokes its credential. Disconnecting a site affects its wallet connection. These controls do not revoke an on-chain allowance or undo a completed action. Exit a terminal session holding the token when finished; unset KEEPKEY_API_KEY removes it from that shell but not from a process already running.

Last updated on