MCP reference

Connect Claude, Codex, Cursor or another MCP client and learn every tool exposed by Clout Browser.

5 min read

On this page

The MCP server lets an AI agent discover and manage profiles. Starting a profile returns its CDP endpoint so a browser-capable agent can drive the actual fingerprinted browser.

Connect your client

  1. Open Clout Browser and MCP & Local API.
  2. Enable the Local API and save its settings.
  3. Install Node.js 22.5 or newer for the bundled MCP server.
  4. In Connect an AI agent, choose your client.
  5. Copy the generated command or configuration and follow the displayed steps.
  6. Check the client’s connection, then ask it to inspect a profile before opening one.
Connect an AI agent card with generated setup command
Use the command generated for this installation.

The separate cloutctl release requires Node 24 or later. Do not confuse that requirement with the MCP card’s minimum.

The setup page offers Claude Code, Claude Desktop, Codex CLI, Cursor, VS Code, Windsurf and Other. Commands and file paths are computed for your installed app and operating system; use those displayed values instead of copying a macOS path onto Windows.

ClientSetup shown by CloutConnection check
Claude Codeclaude mcp add commandRun /mcp
Claude DesktopmcpServers entryQuit completely, reopen and check Connectors
Codex CLIcodex mcp add commandRun codex mcp list
Cursor~/.cursor/mcp.json entryCursor Settings → MCP
VS Codecode --add-mcp commandChat → Agent mode
Windsurf~/.codeium/windsurf/mcp_config.json entryRefresh its MCP panel
OtherGeneric mcpServers entryThe client’s own connection view

Clout’s server uses stdio transport. The client launches node with the bundled clout-mcp.mjs path. The server discovers the running Local API address and reads its token from the local store; the normal generated setup does not embed a token.

Profile targets

Single-profile tools accept profile_id or profile_no. Always supply one: the tool schemas do not require it, and get_profile without a filter can return the first listed row. Start with list_profiles; names and IDs are not interchangeable. Use profile_status to reconnect to an already open browser.

Tool reference

Profiles and folders:

ToolInputsWhat it returns or changes
list_profilesOptional name, group_id, page, limitProfile page; name keeps profiles whose name contains it, ignoring case; limit defaults to 50, capped at 200
get_profileprofile_id or profile_noOne profile record, or “No profile with that id or number.”
profile_statusTargetWhether it is open and its CDP endpoint
start_profileTarget, optional headless, delete_cacheOpens it and returns the endpoint; an open profile returns the existing endpoint
stop_profileTargetCloses its browser and keeps the session
create_profileRequired name; optional group_id (a folder), remark, user_proxy_configNew profile with a fresh fingerprint
update_profileTarget and optional name, remark, group_id, user_proxy_configChanges supplied values and returns the profile as it is afterwards; an open profile can only change its name, note and folder
list_foldersNoneThe sidebar’s folders, with ids and profile counts; Ungrouped (0) is not listed
create_folderRequired nameA new folder, or the existing one with that name (created: false)
rename_folderRequired folder_id, nameThe renamed folder
delete_folderRequired folder_idDeletes the folder; its profiles move to Ungrouped
move_profilesRequired profile_ids, folder_idMoves profiles into a folder; 0 is Ungrouped
list_proxiesNoneSaved proxies and last checks
check_proxyRequired proxy_idConnection outcome and exit location
list_extensionsNoneAvailable extensions and use
browser_statusNoneThe plan’s limits and what this computer uses

Inside an open profile:

ToolInputsWhat it does
list_tabs, open_tab, close_tabTarget, tab_id, urlManage tabs
navigateTarget, tab_id, urlLoad a page and wait for it
read_pageTarget, tab_id, optional mode, max_charsAn outline of the page with a ref for every control
click, type_text, press_key, scrollTarget, tab_id, a ref or selector, text or keyAct on the page
wait_forTarget, tab_id, text or selector, timeout_msWait until it appears
screenshotTarget, tab_id, optional full_pageAn image of the tab
run_scriptTarget, tab_id, expression, optional worldThe JSON value of a JavaScript expression

Page reads and run_script run in an isolated world: they see the page’s DOM and signed-in session, but the page’s own scripts cannot see them run. The page’s JavaScript variables are not visible there; pass world: "page" to run_script when an expression needs them, and the page can then observe it.

Changes made through MCP show in the open app within a moment.

user_proxy_config uses the Local API’s nested proxy fields; see Local API. Omitting it on create means a direct connection.

start_profile defaults to a visible browser. delete_cache defaults to false and requests cache clearing when it closes. A first launch may take minutes while the engine downloads.

Give the agent a bounded job

For example: “List the profiles in this workspace. Open the profile named Creator A · X, check its proxy, then stop it when finished.” The agent should use the returned ID after listing.

A launched browser carries the profile’s session, not an empty testing context. Treat permission to operate it as permission to act through that account. Agree on the job before handing it over.

The MCP tool set does not expose profile deletion, billing changes or fingerprint re-rolling. Those remain deliberate operations through their other product surfaces. delete_folder removes only the folder.

Connection failures

Keep Clout Browser running, the Local API enabled and Node available to the client process. If the app says “The MCP server is missing from this installation. Update or reinstall Clout Browser.”, follow that instruction.

The server finds the app by itself, including a development build and a headless cloutctl serve. If your app data is in a nonstandard location, set CLOUT_APP_SUPPORT_DIR in the client’s environment to the app’s data directory (the one holding api/local_api.json).

A local API port conflict is fixed in Clout, not by pasting a stale port into every client. Troubleshooting has the common cases.

Limits and failures

The MCP client unwraps the Local API envelope. A nonzero code becomes a tool error even when HTTP returned 200, and the error says why, with any credential in the message removed. Normal calls time out after 120 seconds, proxy checks after 60 seconds and starts after 300 seconds. A timeout is not proof that a profile failed to start; use profile_status before retrying.

The server re-reads discovery on each call, so an app restart can change the address without changing your MCP configuration. The server masks recognised password, cookie, token and two-factor-seed keys recursively before returning tool results. Other profile metadata still reaches your MCP client; keep tool output private. Check a profile’s signed-in state in the browser rather than assuming a successful start proves the session is valid.