MCP reference
Connect Claude, Codex, Cursor or another MCP client and learn every tool exposed by Clout Browser.
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
- Open Clout Browser and MCP & Local API.
- Enable the Local API and save its settings.
- Install Node.js 22.5 or newer for the bundled MCP server.
- In Connect an AI agent, choose your client.
- Copy the generated command or configuration and follow the displayed steps.
- Check the client’s connection, then ask it to inspect a profile before opening one.

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.
| Client | Setup shown by Clout | Connection check |
|---|---|---|
| Claude Code | claude mcp add command | Run /mcp |
| Claude Desktop | mcpServers entry | Quit completely, reopen and check Connectors |
| Codex CLI | codex mcp add command | Run codex mcp list |
| Cursor | ~/.cursor/mcp.json entry | Cursor Settings → MCP |
| VS Code | code --add-mcp command | Chat → Agent mode |
| Windsurf | ~/.codeium/windsurf/mcp_config.json entry | Refresh its MCP panel |
| Other | Generic mcpServers entry | The 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:
| Tool | Inputs | What it returns or changes |
|---|---|---|
list_profiles | Optional name, group_id, page, limit | Profile page; name keeps profiles whose name contains it, ignoring case; limit defaults to 50, capped at 200 |
get_profile | profile_id or profile_no | One profile record, or “No profile with that id or number.” |
profile_status | Target | Whether it is open and its CDP endpoint |
start_profile | Target, optional headless, delete_cache | Opens it and returns the endpoint; an open profile returns the existing endpoint |
stop_profile | Target | Closes its browser and keeps the session |
create_profile | Required name; optional group_id (a folder), remark, user_proxy_config | New profile with a fresh fingerprint |
update_profile | Target and optional name, remark, group_id, user_proxy_config | Changes supplied values and returns the profile as it is afterwards; an open profile can only change its name, note and folder |
list_folders | None | The sidebar’s folders, with ids and profile counts; Ungrouped (0) is not listed |
create_folder | Required name | A new folder, or the existing one with that name (created: false) |
rename_folder | Required folder_id, name | The renamed folder |
delete_folder | Required folder_id | Deletes the folder; its profiles move to Ungrouped |
move_profiles | Required profile_ids, folder_id | Moves profiles into a folder; 0 is Ungrouped |
list_proxies | None | Saved proxies and last checks |
check_proxy | Required proxy_id | Connection outcome and exit location |
list_extensions | None | Available extensions and use |
browser_status | None | The plan’s limits and what this computer uses |
Inside an open profile:
| Tool | Inputs | What it does |
|---|---|---|
list_tabs, open_tab, close_tab | Target, tab_id, url | Manage tabs |
navigate | Target, tab_id, url | Load a page and wait for it |
read_page | Target, tab_id, optional mode, max_chars | An outline of the page with a ref for every control |
click, type_text, press_key, scroll | Target, tab_id, a ref or selector, text or key | Act on the page |
wait_for | Target, tab_id, text or selector, timeout_ms | Wait until it appears |
screenshot | Target, tab_id, optional full_page | An image of the tab |
run_script | Target, tab_id, expression, optional world | The 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.