MCP server for AI assistants

Incogniton runs a hosted Model Context Protocol (MCP) server. Connect an AI assistant to it, such as Claude Code, Claude Desktop, Cursor, VS Code or Windsurf, and the assistant can search, create and edit your profiles, proxies, groups and tags, and launch and stop profiles in your Incogniton desktop app.

Unlike the local automation API, the MCP server runs in the cloud and works with your Incogniton account through a personal token. When the assistant launches a profile, the request goes to your desktop app, which must be running and logged in.

Get a token

In the Incogniton app, go to My Account → Settings → MCP Token and click Generate Token. The token starts with mcp_live_.

Connect your AI client

Every client runs the stdio bridge @incogniton/mcp through npx (Node.js 18 or later). The bridge forwards requests to https://v5api.incogniton.com/mcp. Replace mcp_live_YOUR_TOKEN with your token.

claude mcp add incogniton --scope user --env INCOGNITON_MCP_TOKEN=mcp_live_YOUR_TOKEN -- npx -y @incogniton/mcp

For Claude Desktop, Cursor and Windsurf, add the JSON to the client's MCP config file, for example claude_desktop_config.json for Claude Desktop or ~/.cursor/mcp.json for Cursor. For VS Code, add it to .vscode/mcp.json in your workspace. The Incogniton app can also generate these snippets with your token already filled in, under Settings → Automation → MCP.

To check that the bridge can reach the server, run:

npx -y @incogniton/mcp --health

Then restart your AI client. The Incogniton tools appear in its tool list.

Tools

The server provides 19 tools:

Tool results are written for the model: usually a sentence followed by a JSON block. If you call the tools from your own code, parse the JSON block. The automation examples repository has a helper for this, extractJson.

Launch a profile and attach Playwright

1. Launch. Call launch_profile with the profile's profile_browser_ID. This creates a launch request, which your desktop app picks up within seconds. The request expires after timeout_seconds (30 to 300, default 300).
2. Get the DevTools URL. Call get_launch_status with the same profile_browser_ID. When your request is LAUNCHED and the browser is still running, its entry has a cdp_url, for example http://127.0.0.1:55923. If it doesn't, cdp_unavailable_reason says why (for example, the browser was closed). Query by profile, not by request_id: by request id, the tool returns a text summary without cdp_url.
3. Attach Playwright or Puppeteer to the cdp_url. In Playwright, use the profile's own context, browser.contexts()[0], so its cookies and storage are there.
4. Stop. Close the browser over CDP with Browser.close, as in the snippet below. Alternatively, call stop_profile, which works only for profiles launched through MCP. It returns a stop request id; poll get_launch_status with include_stop_requests until that stop request is STOPPED, and match on the stop request's own id rather than the launch's.

import { chromium } from 'playwright'

// cdpUrl: the cdp_url from get_launch_status
const browser = await chromium.connectOverCDP(cdpUrl)

// The profile's own context, with its cookies and storage.
// browser.newContext() would start an empty one.
const context = browser.contexts()[0]
const page = await context.newPage()
await page.goto('https://example.com')

// Close the browser itself; browser.close() would only disconnect.
const cdp = await browser.newBrowserCDPSession()
await cdp.send('Browser.close')

Closing over CDP is the safer way to stop: current app versions terminate the browser on stop_profile, which can lose cookies and localStorage written in the last few seconds. A normal close doesn't.

A complete, runnable version of this flow is the launch-with-mcp-and-attach-playwright example in the automation examples repository. For how profiles keep cookies and storage between runs, see Lifecycle and persistence.

Example prompts

These work in any MCP client. The tools in brackets are the ones the assistant is expected to call.

• "Create 3 profiles called shop-1 to shop-3 in the group Shops, Windows, latest browser." [search_profile_groups → create_profiles]
• "Which profiles use the proxy at 203.0.113.10?" [search_proxies → search_profiles]
• "Clone the profile shop-1 twice." [search_profiles → clone_profile]
• "Launch shop-1 on this computer and give me its DevTools URL." [search_profiles → launch_profile → get_launch_status]
• "Stop shop-1." [stop_profile → get_launch_status]

For work inside pages, a coding agent on the same computer, such as Claude Code, can take the cdp_url and run Playwright, as in the snippet above.

Troubleshooting

Next Steps