MCP server
Let AI agents in Claude, Cursor and other MCP clients open VeilBrowser profiles and drive them over the DevTools Protocol.
veil mcp is a Model Context Protocol
server. An AI agent uses it to find a profile, open it on your computer and get
its Chrome DevTools Protocol address, then drives the browser with a browser
automation server or its own code.
It runs on the computer where the browsers open: the one with the VeilBrowser agent, or one that can reach a worker (see CLI).
Add it to your client
The server speaks MCP over stdio. Every client takes the same command:
{
"mcpServers": {
"veilbrowser": {
"command": "npx",
"args": ["-y", "veilbrowser", "mcp"]
}
}
}| Client | Where the config goes |
|---|---|
| Cursor | .cursor/mcp.json in a project, or ~/.cursor/mcp.json |
| Claude Desktop | claude_desktop_config.json (Settings, Developer, Edit config) |
| Claude Code | claude mcp add veilbrowser -- npx -y veilbrowser mcp |
| VS Code | .vscode/mcp.json, under servers instead of mcpServers |
To use a worker, pass its settings in env:
{
"mcpServers": {
"veilbrowser": {
"command": "npx",
"args": ["-y", "veilbrowser", "mcp"],
"env": {
"VEIL_LOCAL_API_URL": "http://worker-1.internal:38923",
"VEIL_API_KEY": "<worker API_KEY>",
"VEIL_KEY": "<organization API key>"
}
}
}
}Tools
| Tool | What it does |
|---|---|
list_profiles | The organization's profiles, most recently used first, with search, limit and page |
start_profile | Opens a profile (profileId, optional headless) and returns sessionId and webSocketDebuggerUrl |
stop_profile | Closes a browser by session or profile id; its data is saved as it closes |
warm_up_profile | Visits a list of sites in a closed profile, headless, then closes it so the cookies are saved (profileId, urls, optional dwellSec) |
list_sessions | The browsers open now, with their profile and DevTools address |
get_devtools_endpoint | A running browser's WebSocket, HTTP base and each open tab's WebSocket |
Results come back as JSON, as both text and structured content. A failure, such as a profile already open elsewhere, comes back as a tool error the agent can read.
Drive the browser
VeilBrowser opens the browser; another tool clicks and types in it. Pair it with a browser automation MCP server that can attach to an existing browser over CDP, for example Playwright MCP:
{
"mcpServers": {
"veilbrowser": { "command": "npx", "args": ["-y", "veilbrowser", "mcp"] },
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest", "--cdp-endpoint", "http://127.0.0.1:9222"]
}
}
}Playwright MCP takes its endpoint when it starts, so this suits one long-lived
profile: start it once with veil start, read its HTTP address, and put that
in --cdp-endpoint. For an agent that writes its own code, hand it the
webSocketDebuggerUrl from start_profile and let it connect with
chromium.connectOverCDP(url) or puppeteer.connect({ browserWSEndpoint }).
A typical prompt:
Open my "shop-us-01" VeilBrowser profile, check the order status page,
then close the profile.Security
The server can open and close any profile the agent or worker can, so add it only to agents you trust with your browser identities. It listens on nothing: it talks to the agent's loopback API with the agent's local key, which only your user account can read.