MCP Quickstart

What is MCP?

The Model Context Protocol (MCP) allows AI assistants like Claude, ChatGPT and Cline to access external tools and services. By adding the WebRun MCP server, you give these assistants the ability to browse the web autonomously.

Choose your path

There is one server URL for every client:

https://api.webrun.ai/mcp

Claude and ChatGPT connect with that URL and no API key at all — you authorize WebRun once, in the browser. Start at Connect with OAuth.
Everything with a config file (Claude Code, Cursor, Claude Desktop, VS Code, Cline) uses the same URL plus an API-Key header. A second header, Environment-Id, is optional — it decides whether tasks run on a persistent machine or a throwaway one. Start at Connect with an API key.

Your API key travels in a header, never in the URL. That keeps it out of browser history, shell history and proxy logs, and it means you can rotate the key without touching a URL you may have already copied somewhere else.

Connect with OAuth (Claude and ChatGPT)

No API key needed.

Open connector settings

In Claude or ChatGPT, go to Settings → Connectors → Add custom connector.

Paste the server URL

https://api.webrun.ai/mcp

Authorize from WebRun

Approve the connection when prompted. WebRun issues the credentials for you.

If you have more than one environment, the one you pick during authorization becomes the connection’s default — the assistant will use it without being told.

Connect with an API key

Every example below is complete: the same URL, your API key, and the environment you want the assistant to work in. Copy the whole block.

Claude Code

claude mcp add --transport http webrun https://api.webrun.ai/mcp --header "API-Key: YOUR_API_KEY" --header "Environment-Id: 65f0a1b2c3d4e5f60718293a"

--header is repeatable — that is how both values are passed in one command. Or, to share the connection with a project, add this to .mcp.json at the repo root:

{
  "mcpServers": {
    "webrun": {
      "type": "http",
      "url": "https://api.webrun.ai/mcp",
      "headers": {
        "API-Key": "${WEBRUN_API_KEY}",
        "Environment-Id": "65f0a1b2c3d4e5f60718293a"
      }
    }
  }
}

Delete the Environment-Id line to get a fresh disposable machine for every task.

"type": "http" is required. Claude Code reads a url entry with no type as a local command, and the server will not start.

${WEBRUN_API_KEY} is expanded from your environment when the file loads, so the file is safe to commit. The environment ID is not a secret and can stay inline.

Cursor

Add this to ~/.cursor/mcp.json, or .cursor/mcp.json inside a project:

{
  "mcpServers": {
    "webrun": {
      "url": "https://api.webrun.ai/mcp",
      "headers": {
        "API-Key": "${env:WEBRUN_API_KEY}",
        "Environment-Id": "65f0a1b2c3d4e5f60718293a"
      }
    }
  }
}

Delete the Environment-Id line to get a fresh disposable machine for every task. Cursor does not use a type field for remote servers, and its variable syntax is ${env:NAME}.

Claude Desktop

Claude Desktop’s configuration file only supports local (stdio) servers, so connect through Settings → Connectors using the OAuth flow above — no key, no file editing, and you choose the environment during authorization. If you must use the config file, bridge it with mcp-remote:

{
  "mcpServers": {
    "webrun": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote", "https://api.webrun.ai/mcp",
        "--header", "API-Key:${WEBRUN_KEY}",
        "--header", "Environment-Id:65f0a1b2c3d4e5f60718293a"
      ],
      "env": { "WEBRUN_KEY": "YOUR_API_KEY" }
    }
  }
}

Delete the second --header pair to get a fresh disposable machine for every task.

The headers are written without a space after the colon on purpose — mcp-remote splits --header arguments on spaces.

After editing, quit Claude Desktop completely and reopen it.

VS Code

Add this to .vscode/mcp.json — note the top-level key is servers, not mcpServers:

{
  "servers": {
    "webrun": {
      "type": "http",
      "url": "https://api.webrun.ai/mcp",
      "headers": {
        "API-Key": "${input:webrun-api-key}",
        "Environment-Id": "65f0a1b2c3d4e5f60718293a"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "webrun-api-key", "description": "WebRun API key", "password": true }
  ]
}

Delete the Environment-Id line to get a fresh disposable machine for every task. VS Code prompts for the key on first use and stores it securely rather than in the file.

Cline

Open the Cline panel, use the menu in its top-right corner, choose MCP Servers, and edit cline_mcp_settings.json:

{
  "mcpServers": {
    "webrun": {
      "type": "streamableHttp",
      "url": "https://api.webrun.ai/mcp",
      "headers": {
        "API-Key": "YOUR_API_KEY",
        "Environment-Id": "65f0a1b2c3d4e5f60718293a"
      }
    }
  }
}

Delete the Environment-Id line to get a fresh disposable machine for every task.

"type": "streamableHttp" is camelCase with no hyphen. Writing streamable-http, or leaving type out, makes Cline fall back to SSE and the connection fails with a 405.

Cline does not expand environment variables in this file, so the key goes in literally — keep the file out of version control.

Environments

An environment is a persistent remote machine with its own browser, file system, and desktop, so logins, cookies, and downloaded files survive between tasks. The Environment-Id header is optional. Both ways of running are fully supported:

Environment ID	What you get
Provided	Every task runs on that persistent environment. Logins, cookies, downloaded files and browser profile carry over from one task to the next
Omitted	Every task gets its own temporary browser, created when the task starts and discarded when it ends. Nothing carries over

Leaving the header out is a normal configuration, not a broken one. Omit it when every task should start from a clean slate, and add an environment when you need the browser to remember something — a logged-in account, a downloaded file, an installed extension. Where to find the ID: ask the assistant to list your environments, or copy it from the Environment page in the dashboard. It is a 24-character hex string, and it is not a secret — it is safe to commit. Three ways to choose one:

How	When
The `Environment-Id` header	A config file — sets the default for the whole connection
Chosen during OAuth authorization	Claude and ChatGPT connectors, which have no config file
The `environmentId` argument on any task tool	Per task, overriding whatever the connection uses

The per-task argument means you can keep one connection and still send one task to your logged-in shopping profile and the next to a clean machine.

Your First Browser Task

Once configured, you can ask Claude to browse the web: Example Prompts:

“Search Google for Anthropic and summarize the first result”
“Go to example.com and extract all the product prices”
“Navigate to LinkedIn, search for software engineers in SF, and list the top 5 results”

What happens:

Claude recognizes your request requires web browsing
It calls the WebRun MCP tool with your task
An AI agent executes the task in a real browser
Results are returned to Claude
Claude presents the information to you

For multi-step work, ask for a session instead of a one-off task — “Create a browser session, go to Amazon, search for wireless keyboards, and tell me the top 3 results.” The assistant calls create_session once and then send_task for each follow-up, so the browser keeps its place between steps.

Available Tools

The WebRun MCP server exposes 21 tools. Browser tasks

Tool	What it does
`browser_task`	Run a one-off task in a real browser; creates a session, runs, cleans up
`create_session`	Start a persistent session for multi-step work
`send_task`	Send another task to an existing session
`get_task_status`	Check a running task; reports when input is needed
`screenshot`	Capture the current page of a live session
`list_sessions`	List active sessions
`terminate_session`	End a session and free its resources

Controlling a running task

Tool	What it does
`pause_session_task`	Pause the task currently running
`resume_session_task`	Resume a paused task
`stop_session_task`	Cancel the task, keep the session alive
`guardrail_response`	Answer when the agent hits a CAPTCHA, 2FA prompt, or confirmation

Environments

Tool	What it does
`list_environments`	List persistent environments and show which one this connection uses

Workflows — saved, reusable automations

Tool	What it does
`list_workflows` · `get_workflow`	Browse saved workflows and inspect one
`create_workflow` · `update_workflow`	Author and edit them
`trigger_workflow`	Run one now

Scheduled agents — automations that run on a timer

Tool	What it does
`create_agent`	Schedule a recurring or one-time run
`list_agents` · `pause_agent` · `resume_agent`	Manage them

Full MCP Reference →

Troubleshooting

Tools not appearing (Claude Code)

Run claude mcp get webrun. The most common cause is a missing "type": "http" — without it the entry is treated as a local command.

Tools not appearing (Cursor / VS Code)

Confirm the top-level key: Cursor uses mcpServers, VS Code uses servers.

It connects but every task fails

The server lists its tools without a key, so a connection with a missing or wrong key looks healthy until the first task. Check the API-Key header value.

Authentication errors

Keys start with wr_ or enig_. Confirm the key is active in the dashboard and that the account has balance.

”Environment not found”

The ID must be a 24-character hex string belonging to your account. Ask the assistant to list your environments.

Session timeouts

Sessions expire after 5 minutes idle. A single task runs up to 20 minutes by default — pass maxDuration for longer, or split the work.

Claude Code, Cursor and VS Code pick up config changes without a restart. Only Claude Desktop needs a full quit and reopen.

Next Steps

Full MCP Reference

All tools, parameters, and advanced patterns

Multi-Task Workflows

Chain multiple browser tasks

Handling Guardrails

Respond to human-in-the-loop requests

Video Streaming

Watch browser sessions live

Getting Started

Concepts

Usage Guides

Integrations

Environments

API Reference

Capabilities

Troubleshooting

What is MCP?

Choose your path

Connect with OAuth (Claude and ChatGPT)

Connect with an API key

Claude Code

Cursor

Claude Desktop

VS Code

Cline

Environments

Your First Browser Task

Available Tools

Troubleshooting

Tools not appearing (Claude Code)

Tools not appearing (Cursor / VS Code)

It connects but every task fails

Authentication errors

”Environment not found”

Session timeouts

Next Steps

Full MCP Reference

Multi-Task Workflows

Handling Guardrails

Video Streaming

​What is MCP?

​Choose your path

​Connect with OAuth (Claude and ChatGPT)

​Connect with an API key

​Claude Code

​Cursor

​Claude Desktop

​VS Code

​Cline

​Environments

​Your First Browser Task

​Available Tools

​Troubleshooting

​Tools not appearing (Claude Code)

​Tools not appearing (Cursor / VS Code)

​It connects but every task fails

​Authentication errors

​”Environment not found”

​Session timeouts

​Next Steps

Full MCP Reference

Multi-Task Workflows

Handling Guardrails

Video Streaming

What is MCP?

Choose your path

Connect with OAuth (Claude and ChatGPT)

Connect with an API key

Claude Code

Cursor

Claude Desktop

VS Code

Cline

Environments

Your First Browser Task

Available Tools

Troubleshooting

Tools not appearing (Claude Code)

Tools not appearing (Cursor / VS Code)

It connects but every task fails

Authentication errors

”Environment not found”

Session timeouts

Next Steps