Everything the MCP connector and the Python client do goes through one JSON-RPC endpoint on your PC. You can call it directly from any language.
Basics
Wisp listens on 127.0.0.1, default port 9777 (if it is taken, the next free port up to 9797).
Port, token and URL are written to %APPDATA%\Wisp\api.json while Wisp runs. The token itself is kept in api-token in the same folder.
Every call needs Authorization: Bearer <token>. Requests with an Origin header (that is, from web pages) and requests to any host name other than 127.0.0.1 or localhost are refused.
GET /health answers without a token: {"name":"Wisp","ok":true}.
Responses are {"result": ...} or {"error": "..."}.
Name, version, Chromium and Electron versions, window visibility, ad blocker state, tab count, current profile, graphics mode, data folder.
profiles.list
All profiles with name, id, whether current, and tab count.
profiles.add
name. Creates a profile.
profiles.remove
name. Closes its tabs and deletes its logins and site data. The first profile cannot be removed.
profiles.switch
name. Shows that profile’s tabs.
app.quit
Quits Wisp.
Tabs
Method
Parameters and result
tabs.list
All tabs: tab, url, title, loading, active, agent, asleep, profile.
tabs.new
url, profile, activate (default false), muted, wait (default true), timeout. Opens a background tab marked as an agent tab and waits for it to load.
tabs.close
tab.
tabs.activate
tab. Makes it the visible tab.
tabs.sleep
tab. Unloads the page to free memory.
Navigation
Method
Parameters and result
navigate
url (an address or a search phrase), tab (optional: defaults to the tab an agent used last, then the active tab), wait, timeout.
back / forward / reload
tab (optional: defaults to the tab an agent used last, then the active tab)
Reading
Method
Parameters and result
text
tab (optional: defaults to the tab an agent used last, then the active tab), selector, max_chars (default 50,000). Visible text, main content first.
html
tab (optional: defaults to the tab an agent used last, then the active tab), selector, max_chars (default 200,000).
snapshot
tab (optional: defaults to the tab an agent used last, then the active tab), viewport_only, max (default 400). Interactive elements with ref, role, name, and value, checked, href, disabled where relevant. Password field values are never included.
screenshot
tab (optional: defaults to the tab an agent used last, then the active tab), full_page, format (png or jpeg), quality, path. Returns base64, or saves to path. Works while Wisp is in the background.
dialogs
tab (optional: defaults to the tab an agent used last, then the active tab). JavaScript alerts and confirms the page showed (they are accepted automatically once DevTools Protocol is attached).
Acting
Method
Parameters and result
click
tab (optional: defaults to the tab an agent used last, then the active tab), and one of ref, selector, text, or x/y.
type
text, tab (optional: defaults to the tab an agent used last, then the active tab), ref or selector (omit both for the focused element), clear (default true), submit.
key
key, e.g. Enter, Escape, Tab, ArrowDown, PageDown, ctrl+a. tab (optional: defaults to the tab an agent used last, then the active tab).
scroll
tab (optional: defaults to the tab an agent used last, then the active tab), dy (default most of a screen), dx.
wait
tab (optional: defaults to the tab an agent used last, then the active tab), and selector, text or ms; timeout (default 15 s).
eval
code, tab (optional: defaults to the tab an agent used last, then the active tab), timeout. Runs JavaScript in the page; promises are awaited.
cdp
method, params, tab (optional: defaults to the tab an agent used last, then the active tab). Raw Chrome DevTools Protocol.
Window and UI
Method
Parameters and result
window.show / window.hide
Show the window, or move it out of sight (Wisp keeps running).
window.screenshot
Capture Wisp’s own UI to a PNG, for diagnostics.
ui.eval / ui.key
Run script in, or send a key to, the browser’s own UI (used for testing).
Sleeping tabs
Tabs can be asleep ("asleep": true in tabs.list): restored tabs and tabs unloaded by the memory saver. Any page method on a sleeping tab wakes it and waits for it to load. Tabs an agent used recently are not put to sleep by the memory saver.
Limits
snapshot covers the main document and open shadow roots, not cross-origin iframes (use cdp or eval for those).
The API cannot send input events to a tab while DevTools is open on it; clicks fall back to scripted clicks.
Saved passwords are not reachable through the API, and Wisp will not fill a password into a tab an agent drove in the last few seconds.
MCP tool names
The MCP connector maps its tools onto these methods: wisp_tabs → tabs.list, wisp_open → tabs.new, wisp_read → text, wisp_navigate → navigate, and so on. See the tool list.