MCP server · Docs

The Boxline MCP server lets Claude, Cursor and other Model Context Protocol clients use sessions as tools: the model can browse, run commands in the shell and work with files on one isolated machine, while you watch in the live view.

The server runs locally over stdio with npx -y @boxline/mcp and needs two environment variables: BOXLINE_API_KEY (your API key) and BOXLINE_API_URL (the API base URL, https://api.staging.boxline.dev).

Claude Code

Shell

claude mcp add boxline \
  -e BOXLINE_API_KEY=your-api-key \
  -e BOXLINE_API_URL=https://api.staging.boxline.dev \
  -- npx -y @boxline/mcp

Claude Desktop

Add the server to claude_desktop_config.json and restart the app:

claude_desktop_config.json

{
  "mcpServers": {
    "boxline": {
      "command": "npx",
      "args": ["-y", "@boxline/mcp"],
      "env": {
        "BOXLINE_API_KEY": "your-api-key",
        "BOXLINE_API_URL": "https://api.staging.boxline.dev"
      }
    }
  }
}

Cursor

Use the same block in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json to enable it everywhere:

.cursor/mcp.json

{
  "mcpServers": {
    "boxline": {
      "command": "npx",
      "args": ["-y", "@boxline/mcp"],
      "env": {
        "BOXLINE_API_KEY": "your-api-key",
        "BOXLINE_API_URL": "https://api.staging.boxline.dev"
      }
    }
  }
}

Other clients

Any client that can launch a stdio MCP server works. Run npx -y @boxline/mcp with both environment variables set.

Tools

Every tool except session_create and fetch_url takes an optional sessionId. Without one, the server uses a default session, creating one with a browser and a Python shell the first time it is needed, so the model can simply call browser_navigate and start working.

Tool	What it does
`session_create`	Create a session (browser, optional shell, timeout, optional proxy) and make it the default.
`session_close`	Release a session; billing stops.
`session_move`	Move a session to a fresh machine, keeping tabs, logins, form values and files.
`browser_navigate`	Open a URL.
`browser_click`	Click by selector (e.g. text=Sign in) or page coordinates.
`browser_type`	Type text, optionally into an element.
`browser_press`	Press a key, e.g. Enter.
`browser_screenshot`	Screenshot the current tab.
`browser_read`	Read the current page as markdown or text.
`run_command`	Run a bash command in the persistent shell (downloads are in ./downloads).
`run_playwright`	Run Playwright code inside the session, next to its browser (page, context, browser and env are in scope).
`list_files`	List files in the workspace.
`read_file`	Read a text file from the workspace.
`write_file`	Write a text file into the workspace.
`fetch_url`	Fetch a page as markdown, HTML or text, without a session.

Browse through a proxy

session_create takes three optional proxy parameters, so you can ask the model to “open a session with a residential proxy in Germany”.

Parameter	Description
`proxyType`	`"residential"` (home IPs) or `"datacenter"`. Without it, no proxy.
`proxyCountry`	Two-letter country code, e.g. `"DE"`.
`proxyCity`	Residential only, e.g. `"berlin"`. Needs `proxyCountry`.

The session keeps one IP, and only the browser uses the proxy: shell commands connect directly. The default session that tools create on their own has no proxy, so call session_create first. US states, your own proxy and the shell option are available through the API and SDKs.

These docs describe a beta API. Endpoints, fields and SDK methods may change before general availability; breaking changes will be listed in the changelog.