diff --git a/docs.json b/docs.json index 5fe64f0..8e839d8 100644 --- a/docs.json +++ b/docs.json @@ -273,8 +273,58 @@ }, { "tab": "MCP", - "pages": [ - "reference/mcp-server" + "groups": [ + { + "group": "Getting Started", + "pages": [ + "reference/mcp-server", + "reference/mcp-server/transports", + "reference/mcp-server/authentication" + ] + }, + { + "group": "Connect Your Client", + "pages": [ + "reference/mcp-server/clients/claude", + "reference/mcp-server/clients/cursor", + "reference/mcp-server/clients/opencode", + "reference/mcp-server/clients/goose", + "reference/mcp-server/clients/vscode", + "reference/mcp-server/clients/windsurf", + "reference/mcp-server/clients/zed", + "reference/mcp-server/clients/smithery", + "reference/mcp-server/clients/others" + ] + }, + { + "group": "Tools", + "pages": [ + "reference/mcp-server/tools/manage-browsers", + "reference/mcp-server/tools/manage-profiles", + "reference/mcp-server/tools/manage-browser-pools", + "reference/mcp-server/tools/manage-proxies", + "reference/mcp-server/tools/manage-extensions", + "reference/mcp-server/tools/manage-apps", + "reference/mcp-server/tools/computer-action", + "reference/mcp-server/tools/execute-playwright-code", + "reference/mcp-server/tools/exec-command", + "reference/mcp-server/tools/search-docs" + ] + }, + { + "group": "Resources & Prompts", + "pages": [ + "reference/mcp-server/resources", + "reference/mcp-server/prompts" + ] + }, + { + "group": "Reference", + "pages": [ + "reference/mcp-server/troubleshooting", + "reference/mcp-server/examples" + ] + } ] }, { diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx index 6182502..b14cffd 100644 --- a/reference/mcp-server.mdx +++ b/reference/mcp-server.mdx @@ -5,363 +5,51 @@ description: "Access Kernel's cloud-based browsers via MCP" Our Model Context Protocol (MCP) server lets any compatible AI model or agent launch Chromium browsers, execute Playwright code, capture video replays, and automate web interactions from Kernel's cloud platform via a single secure endpoint. -## Setup Instructions - -### General (Transports) - -- Streamable HTTP (recommended): `https://mcp.onkernel.com/mcp` -- stdio via `mcp-remote` (for clients without remote MCP support): `npx -y mcp-remote https://mcp.onkernel.com/mcp` - -Use the streamable HTTP endpoint where supported for increased reliability. If your client does not support remote MCP, use `mcp-remote` over stdio. - -Kernel's server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with dynamic client registration. - -## Authentication - -### OAuth (Recommended) - -The MCP server uses OAuth 2.1 for user authentication. When you connect through supported clients, you'll be prompted to authorize access via your browser. - -### API Key Authentication - -For programmatic access or service-to-service authentication, you can use your Kernel API key instead of OAuth. - -Add your API key to the MCP configuration: - -```json -{ - "mcpServers": { - "kernel": { - "url": "https://mcp.onkernel.com/mcp", - "headers": { - "Authorization": "Bearer YOUR_KERNEL_API_KEY" - } - } - } -} -``` - -The server automatically detects non-JWT tokens and treats them as API keys. - -API key authentication is useful for: -- Automated workflows and CI/CD pipelines -- Server-to-server integrations -- Environments where OAuth flows are not practical - -API keys bypass the OAuth flow but still require valid Kernel credentials. Ensure your API key is kept secure and not exposed in client-side code. - -## Connect in your client - - -**Quick setup**: Use the Kernel CLI to automatically configure MCP for your tool: `kernel mcp install --target `. See the [CLI MCP documentation](/reference/cli/mcp) for details. - - -### Claude - -Our remote MCP server is not compatible with the method Free users of Claude use to add MCP servers. - -#### Pro, Max, Team & Enterprise (Claude.ai and Claude Desktop) - -1. Go to **Settings → Connectors → Add custom connector**. -2. Enter: **Integration name:** `Kernel`, **Integration URL:** `https://mcp.onkernel.com/mcp`, then click **Add**. -3. In **Settings → Connectors**, click **Connect** next to `Kernel` to launch OAuth and approve. -4. In chat, click **Search and tools** and enable the Kernel tools if needed. - -On Claude for Work (Team/Enterprise), only Primary Owners or Owners can enable custom connectors for the org. After it's configured, each user still needs to go to **Settings → Connectors** and click **Connect** to authorize it for their account. - -#### Claude Code CLI - -**Using Kernel CLI (recommended):** -```bash -kernel mcp install --target claude-code -# Then in the REPL run once to authenticate: -/mcp -``` - -**Manual setup:** -```bash -claude mcp add --transport http kernel https://mcp.onkernel.com/mcp -# Then in the REPL run once to authenticate: -/mcp -``` - -### Cursor - -**Using Kernel CLI (recommended):** -```bash -kernel mcp install --target cursor -``` - -**One-click install:** -Click [here](https://cursor.com/en/install-mcp?name=Kernel&config=eyJ1cmwiOiAiaHR0cHM6Ly9tY3Aub25rZXJuZWwuY29tL21jcCJ9) to install Kernel on Cursor. - -#### Manual setup - -1. Press **⌘/Ctrl Shift J**. -2. Go to **MCP & Integrations → New MCP server**. -3. Add this configuration: - -```json -{ - "mcpServers": { - "kernel": { - "url": "https://mcp.onkernel.com/mcp" - } - } -} -``` - -4. Save. The server will appear in Tools. - -### OpenCode - -Add the following to your `~/.config/opencode/opencode.jsonc`: - -```jsonc -{ - "mcp": { - "kernel": { - "type": "remote", - "url": "https://mcp.onkernel.com/mcp" - } - } -} -``` - -Then authenticate using the OpenCode CLI: - -```bash -# Authenticate with Kernel -opencode mcp auth kernel - -# If you need to re-authenticate, first logout then auth again -opencode mcp logout kernel -opencode mcp auth kernel -``` - -### Goose - -**Using Kernel CLI (recommended):** -```bash -kernel mcp install --target goose -``` -The command will display the YAML configuration to add to your Goose config file. - -**One-click install:** -Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fmcp.onkernel.com%2Fmcp&timeout=300&id=kernel&name=Kernel&description=Access%20Kernel%27s%20cloud-based%20browsers%20via%20MCP) to install Kernel on Goose in one click. - -#### Goose Desktop - -1. Click `Extensions` in the sidebar of the Goose Desktop. -2. Click `Add custom extension`. -3. On the `Add custom extension` modal, enter: - - **Extension Name**: `Kernel` - - **Type**: `STDIO` - - **Description**: `Access Kernel's cloud-based browsers via MCP` - - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp` - - **Timeout**: `300` -4. Click `Save Changes` button. - -#### Goose CLI - -1. Run the following command: - ```bash - goose configure - ``` -2. Select `Add Extension` from the menu. -3. Choose `Command-line Extension`. -4. Follow the prompts: - - **Extension name**: `Kernel` - - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp` - - **Timeout**: `300` - - **Description**: `Access Kernel's cloud-based browsers via MCP` - -### Visual Studio Code - -**Using Kernel CLI (recommended):** -```bash -kernel mcp install --target vscode -``` - -**Manual setup:** - -Add to your VS Code settings.json: -```json -{ - "mcpServers": { - "kernel": { - "url": "https://mcp.onkernel.com/mcp", - "type": "http" - } - } -} -``` - -Or use the UI: -1. Press **⌘/Ctrl Shift P** → search **MCP: Add Server**. -2. Select **HTTP (HTTP or Server-Sent Events)**. -3. Enter: `https://mcp.onkernel.com/mcp` -4. Name the server **Kernel** → Enter. - -### Windsurf - -**Using Kernel CLI (recommended):** -```bash -kernel mcp install --target windsurf -``` - -**Manual setup:** - -1. Press **⌘/Ctrl ,** to open settings. -2. Navigate **Cascade → MCP servers → View raw config**. -3. Paste: - -```json -{ - "mcpServers": { - "kernel": { - "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] - } - } -} -``` - -4. On **Manage MCPs**, click **Refresh** to load Kernel MCP. - -### Zed - -**Using Kernel CLI (recommended):** -```bash -kernel mcp install --target zed -``` - -**Manual setup:** - -1. Press **⌘/Ctrl ,** to open settings. -2. Paste: - -```json -{ - "context_servers": { - "kernel": { - "source": "custom", - "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] - } - } -} -``` - -### Smithery - -You can connect directly to `https://mcp.onkernel.com/mcp`, or use Smithery as a proxy using its provided URL. - -- Use Smithery URL in any MCP client: - 1. Open [Smithery: Kernel](https://smithery.ai/server/kernel). - 2. Copy the URL from "Get connection URL". - 3. Paste it into your MCP client's "Add server" flow. - -- Use Kernel in Smithery's Playground MCP client: - 1. Open [Smithery Playground](https://smithery.ai/playground). - 2. Click "Add servers", search for "Kernel", and add it. - 3. Sign in and authorize Kernel when prompted. - -### Others - -Many other MCP-capable tools accept: - -- **Command:** `npx` -- **Arguments:** `-y mcp-remote https://mcp.onkernel.com/mcp` - -```json -{ - "kernel": { - "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] - } -} -``` - -Configure these values wherever the tool expects MCP server settings. - -## Tools - -Each Kernel feature has a single `manage_*` tool with an `action` parameter, keeping the tool set small and consistent. Four standalone tools handle high-frequency workflows. - -### `manage_*` tools - -- `manage_browsers` - Create, list, get, and delete browser sessions. Supports headless/stealth modes, profiles, proxies, viewports, extensions, and SSH tunneling. -- `manage_profiles` - Setup (with guided live browser session), list, and delete browser profiles for persisting cookies and logins. -- `manage_browser_pools` - Create, list, get, delete, and flush pools of pre-warmed browsers. Acquire and release browsers from pools. -- `manage_proxies` - Create, list, and delete proxy configurations (datacenter, ISP, residential, mobile, custom). -- `manage_extensions` - List and delete uploaded browser extensions. -- `manage_apps` - List apps, invoke actions, get/list deployments, and get invocation results. - -### Standalone tools - -- `computer_action` - Mouse, keyboard, and screenshot controls for browser sessions (click, type, press_key, scroll, move, get_position, screenshot). -- `execute_playwright_code` - Execute Playwright/TypeScript code against a browser with automatic video replay and cleanup. -- `exec_command` - Run shell commands inside a browser VM. Returns decoded stdout/stderr. -- `search_docs` - Search Kernel platform documentation and guides. - -## Resources - -- `browsers://` - Access browser sessions (list all or get specific session) -- `browser_pools://` - Access browser pools (list all or get specific pool) -- `profiles://` - Access browser profiles (list all or get specific profile) -- `apps://` - Access deployed apps (list all or get specific app) - -## Prompts - -- `kernel-concepts` - Get explanations of Kernel's core concepts (browsers, apps, overview) -- `debug-browser-session` - Get a comprehensive debugging guide for troubleshooting browser sessions (VM issues, network problems, Chrome errors) - -## Troubleshooting - -- Cursor clean reset: ⌘/Ctrl Shift P → run `Cursor: Clear All MCP Tokens` (resets all MCP servers and auth; re-enable Kernel and re-authenticate). -- Clear saved auth and retry: `rm -rf ~/.mcp-auth` -- Ensure a recent Node.js version when using `npx mcp-remote` -- If behind strict networks, try stdio via `mcp-remote`, or explicitly set the transport your client supports - -## Examples - -### Invoke apps from anywhere - -``` -Human: Run my web-scraper app to get data from reddit.com -Assistant: I'll execute your web-scraper action with reddit.com as the target. -[Uses manage_apps tool with action: "invoke" to run your deployed app in the cloud] -``` - -### Execute Playwright code dynamically - -``` -Human: Go to example.com and get me the page title -Assistant: I'll execute Playwright code to navigate to the site and retrieve the title. -[Uses execute_playwright_code tool with code: "await page.goto('https://example.com'); return await page.title();"] -Returns: { success: true, result: "Example Domain", replay_url: "https://..." } -``` - -### Set up browser profiles for authentication - -``` -Human: Set up a profile for my work accounts -Assistant: I'll create a profile and guide you through the setup process. -[Uses manage_profiles tool with action: "setup"] - -Human: I'm done setting up my accounts -Assistant: Perfect! I'll close the browser session and save your profile. -[Uses manage_browsers tool with action: "delete" to save profile] -``` - -### Debug a browser session - -Attach the `debug-browser-session` prompt to your conversation first, then ask for help debugging. - -``` -Human: [Attaches debug-browser-session prompt with session_id and issue_description] - Help me debug this browser session. -Assistant: [Follows the debugging guide from the prompt: uses Kernel CLI to check session status, - read VM logs, test network connectivity, and diagnose issues] -``` +The server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with dynamic client registration. + +## Quick start + + + + Point your client at the streamable HTTP endpoint, or use the [Kernel CLI](/reference/cli/mcp) to configure it for you: + + ```bash + kernel mcp install --target + ``` + + + Authorize access through your browser when prompted. See [Authentication](/reference/mcp-server/authentication) for OAuth and API key options. + + + Use the [tools](/reference/mcp-server/tools/manage-browsers) to launch browsers, run Playwright code, and invoke your apps. + + + +## Explore + + + + Streamable HTTP and stdio endpoints. + + + OAuth 2.1 and API key authentication. + + + Setup for Claude, Cursor, VS Code, and more. + + + Browsers, profiles, proxies, apps, and more. + + + Read browsers, pools, profiles, and apps. + + + Prebuilt prompts for concepts and debugging. + + + Fix connection and authentication issues. + + + See the server in action. + + diff --git a/reference/mcp-server/authentication.mdx b/reference/mcp-server/authentication.mdx new file mode 100644 index 0000000..d4066d1 --- /dev/null +++ b/reference/mcp-server/authentication.mdx @@ -0,0 +1,37 @@ +--- +title: "Authentication" +description: "Authenticate to the Kernel MCP server with OAuth or an API key" +--- + +## OAuth (recommended) + +The MCP server uses OAuth 2.1 for user authentication. When you connect through supported clients, you're prompted to authorize access via your browser. + +## API key authentication + +For programmatic access or service-to-service authentication, you can use your Kernel API key instead of OAuth. + +Add your API key to the MCP configuration: + +```json +{ + "mcpServers": { + "kernel": { + "url": "https://mcp.onkernel.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_KERNEL_API_KEY" + } + } + } +} +``` + +The server automatically detects non-JWT tokens and treats them as API keys. + +API key authentication is useful for: + +- Automated workflows and CI/CD pipelines +- Server-to-server integrations +- Environments where OAuth flows are not practical + +API keys bypass the OAuth flow but still require valid Kernel credentials. Keep your API key secure and don't expose it in client-side code. diff --git a/reference/mcp-server/clients/claude.mdx b/reference/mcp-server/clients/claude.mdx new file mode 100644 index 0000000..5d1c2c9 --- /dev/null +++ b/reference/mcp-server/clients/claude.mdx @@ -0,0 +1,33 @@ +--- +title: "Claude" +description: "Connect Claude.ai, Claude Desktop, and Claude Code to the Kernel MCP server" +--- + +Our remote MCP server isn't compatible with the method Free users of Claude use to add MCP servers. + +## Pro, Max, Team & Enterprise (Claude.ai and Claude Desktop) + +1. Go to **Settings → Connectors → Add custom connector**. +2. Enter: **Integration name:** `Kernel`, **Integration URL:** `https://mcp.onkernel.com/mcp`, then click **Add**. +3. In **Settings → Connectors**, click **Connect** next to `Kernel` to launch OAuth and approve. +4. In chat, click **Search and tools** and enable the Kernel tools if needed. + +On Claude for Work (Team/Enterprise), only Primary Owners or Owners can enable custom connectors for the org. After it's configured, each user still needs to go to **Settings → Connectors** and click **Connect** to authorize it for their account. + +## Claude Code CLI + +**Using Kernel CLI (recommended):** + +```bash +kernel mcp install --target claude-code +# Then in the REPL run once to authenticate: +/mcp +``` + +**Manual setup:** + +```bash +claude mcp add --transport http kernel https://mcp.onkernel.com/mcp +# Then in the REPL run once to authenticate: +/mcp +``` diff --git a/reference/mcp-server/clients/cursor.mdx b/reference/mcp-server/clients/cursor.mdx new file mode 100644 index 0000000..122150f --- /dev/null +++ b/reference/mcp-server/clients/cursor.mdx @@ -0,0 +1,31 @@ +--- +title: "Cursor" +description: "Connect Cursor to the Kernel MCP server" +--- + +**Using Kernel CLI (recommended):** + +```bash +kernel mcp install --target cursor +``` + +**One-click install:** +Click [here](https://cursor.com/en/install-mcp?name=Kernel&config=eyJ1cmwiOiAiaHR0cHM6Ly9tY3Aub25rZXJuZWwuY29tL21jcCJ9) to install Kernel on Cursor. + +## Manual setup + +1. Press **⌘/Ctrl Shift J**. +2. Go to **MCP & Integrations → New MCP server**. +3. Add this configuration: + +```json +{ + "mcpServers": { + "kernel": { + "url": "https://mcp.onkernel.com/mcp" + } + } +} +``` + +4. Save. The server will appear in Tools. diff --git a/reference/mcp-server/clients/goose.mdx b/reference/mcp-server/clients/goose.mdx new file mode 100644 index 0000000..fbe8c95 --- /dev/null +++ b/reference/mcp-server/clients/goose.mdx @@ -0,0 +1,41 @@ +--- +title: "Goose" +description: "Connect Goose Desktop and Goose CLI to the Kernel MCP server" +--- + +**Using Kernel CLI (recommended):** + +```bash +kernel mcp install --target goose +``` + +The command will display the YAML configuration to add to your Goose config file. + +**One-click install:** +Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fmcp.onkernel.com%2Fmcp&timeout=300&id=kernel&name=Kernel&description=Access%20Kernel%27s%20cloud-based%20browsers%20via%20MCP) to install Kernel on Goose in one click. + +## Goose Desktop + +1. Click `Extensions` in the sidebar of the Goose Desktop. +2. Click `Add custom extension`. +3. On the `Add custom extension` modal, enter: + - **Extension Name**: `Kernel` + - **Type**: `STDIO` + - **Description**: `Access Kernel's cloud-based browsers via MCP` + - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp` + - **Timeout**: `300` +4. Click `Save Changes` button. + +## Goose CLI + +1. Run the following command: + ```bash + goose configure + ``` +2. Select `Add Extension` from the menu. +3. Choose `Command-line Extension`. +4. Follow the prompts: + - **Extension name**: `Kernel` + - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp` + - **Timeout**: `300` + - **Description**: `Access Kernel's cloud-based browsers via MCP` diff --git a/reference/mcp-server/clients/opencode.mdx b/reference/mcp-server/clients/opencode.mdx new file mode 100644 index 0000000..3c239dc --- /dev/null +++ b/reference/mcp-server/clients/opencode.mdx @@ -0,0 +1,28 @@ +--- +title: "OpenCode" +description: "Connect OpenCode to the Kernel MCP server" +--- + +Add the following to your `~/.config/opencode/opencode.jsonc`: + +```jsonc +{ + "mcp": { + "kernel": { + "type": "remote", + "url": "https://mcp.onkernel.com/mcp" + } + } +} +``` + +Then authenticate using the OpenCode CLI: + +```bash +# Authenticate with Kernel +opencode mcp auth kernel + +# If you need to re-authenticate, first logout then auth again +opencode mcp logout kernel +opencode mcp auth kernel +``` diff --git a/reference/mcp-server/clients/others.mdx b/reference/mcp-server/clients/others.mdx new file mode 100644 index 0000000..404e51c --- /dev/null +++ b/reference/mcp-server/clients/others.mdx @@ -0,0 +1,20 @@ +--- +title: "Other Clients" +description: "Connect any MCP-capable tool to the Kernel MCP server" +--- + +Many other MCP-capable tools accept: + +- **Command:** `npx` +- **Arguments:** `-y mcp-remote https://mcp.onkernel.com/mcp` + +```json +{ + "kernel": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] + } +} +``` + +Configure these values wherever the tool expects MCP server settings. diff --git a/reference/mcp-server/clients/smithery.mdx b/reference/mcp-server/clients/smithery.mdx new file mode 100644 index 0000000..f980d4c --- /dev/null +++ b/reference/mcp-server/clients/smithery.mdx @@ -0,0 +1,18 @@ +--- +title: "Smithery" +description: "Connect to the Kernel MCP server through Smithery" +--- + +You can connect directly to `https://mcp.onkernel.com/mcp`, or use Smithery as a proxy using its provided URL. + +## Use the Smithery URL in any MCP client + +1. Open [Smithery: Kernel](https://smithery.ai/server/kernel). +2. Copy the URL from "Get connection URL". +3. Paste it into your MCP client's "Add server" flow. + +## Use Kernel in Smithery's Playground MCP client + +1. Open [Smithery Playground](https://smithery.ai/playground). +2. Click "Add servers", search for "Kernel", and add it. +3. Sign in and authorize Kernel when prompted. diff --git a/reference/mcp-server/clients/vscode.mdx b/reference/mcp-server/clients/vscode.mdx new file mode 100644 index 0000000..ab50a93 --- /dev/null +++ b/reference/mcp-server/clients/vscode.mdx @@ -0,0 +1,32 @@ +--- +title: "Visual Studio Code" +description: "Connect Visual Studio Code to the Kernel MCP server" +--- + +**Using Kernel CLI (recommended):** + +```bash +kernel mcp install --target vscode +``` + +**Manual setup:** + +Add to your VS Code settings.json: + +```json +{ + "mcpServers": { + "kernel": { + "url": "https://mcp.onkernel.com/mcp", + "type": "http" + } + } +} +``` + +Or use the UI: + +1. Press **⌘/Ctrl Shift P** → search **MCP: Add Server**. +2. Select **HTTP (HTTP or Server-Sent Events)**. +3. Enter: `https://mcp.onkernel.com/mcp` +4. Name the server **Kernel** → Enter. diff --git a/reference/mcp-server/clients/windsurf.mdx b/reference/mcp-server/clients/windsurf.mdx new file mode 100644 index 0000000..01b5ea7 --- /dev/null +++ b/reference/mcp-server/clients/windsurf.mdx @@ -0,0 +1,29 @@ +--- +title: "Windsurf" +description: "Connect Windsurf to the Kernel MCP server" +--- + +**Using Kernel CLI (recommended):** + +```bash +kernel mcp install --target windsurf +``` + +**Manual setup:** + +1. Press **⌘/Ctrl ,** to open settings. +2. Navigate **Cascade → MCP servers → View raw config**. +3. Paste: + +```json +{ + "mcpServers": { + "kernel": { + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] + } + } +} +``` + +4. On **Manage MCPs**, click **Refresh** to load Kernel MCP. diff --git a/reference/mcp-server/clients/zed.mdx b/reference/mcp-server/clients/zed.mdx new file mode 100644 index 0000000..0335b8a --- /dev/null +++ b/reference/mcp-server/clients/zed.mdx @@ -0,0 +1,27 @@ +--- +title: "Zed" +description: "Connect Zed to the Kernel MCP server" +--- + +**Using Kernel CLI (recommended):** + +```bash +kernel mcp install --target zed +``` + +**Manual setup:** + +1. Press **⌘/Ctrl ,** to open settings. +2. Paste: + +```json +{ + "context_servers": { + "kernel": { + "source": "custom", + "command": "npx", + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] + } + } +} +``` diff --git a/reference/mcp-server/examples.mdx b/reference/mcp-server/examples.mdx new file mode 100644 index 0000000..0b779cd --- /dev/null +++ b/reference/mcp-server/examples.mdx @@ -0,0 +1,44 @@ +--- +title: "Examples" +description: "See the Kernel MCP server in action" +--- + +## Invoke apps from anywhere + +``` +Human: Run my web-scraper app to get data from reddit.com +Assistant: I'll execute your web-scraper action with reddit.com as the target. +[Uses manage_apps tool with action: "invoke" to run your deployed app in the cloud] +``` + +## Execute Playwright code dynamically + +``` +Human: Go to example.com and get me the page title +Assistant: I'll execute Playwright code to navigate to the site and retrieve the title. +[Uses execute_playwright_code tool with code: "await page.goto('https://example.com'); return await page.title();"] +Returns: { success: true, result: "Example Domain", replay_url: "https://..." } +``` + +## Set up browser profiles for authentication + +``` +Human: Set up a profile for my work accounts +Assistant: I'll create a profile and guide you through the setup process. +[Uses manage_profiles tool with action: "setup"] + +Human: I'm done setting up my accounts +Assistant: Perfect! I'll close the browser session and save your profile. +[Uses manage_browsers tool with action: "delete" to save profile] +``` + +## Debug a browser session + +Attach the `debug-browser-session` prompt to your conversation first, then ask for help debugging. + +``` +Human: [Attaches debug-browser-session prompt with session_id and issue_description] + Help me debug this browser session. +Assistant: [Follows the debugging guide from the prompt: uses Kernel CLI to check session status, + read VM logs, test network connectivity, and diagnose issues] +``` diff --git a/reference/mcp-server/prompts.mdx b/reference/mcp-server/prompts.mdx new file mode 100644 index 0000000..6b8dae3 --- /dev/null +++ b/reference/mcp-server/prompts.mdx @@ -0,0 +1,11 @@ +--- +title: "Prompts" +description: "Prebuilt prompts for Kernel concepts and debugging" +--- + +The Kernel MCP server ships prebuilt prompts you can attach to a conversation. + +| Prompt | Description | +|--------|-------------| +| `kernel-concepts` | Get explanations of Kernel's core concepts (browsers, apps, overview). | +| `debug-browser-session` | Get a comprehensive debugging guide for troubleshooting browser sessions (VM issues, network problems, Chrome errors). | diff --git a/reference/mcp-server/resources.mdx b/reference/mcp-server/resources.mdx new file mode 100644 index 0000000..f9ca098 --- /dev/null +++ b/reference/mcp-server/resources.mdx @@ -0,0 +1,13 @@ +--- +title: "Resources" +description: "Read browsers, pools, profiles, and apps as MCP resources" +--- + +The Kernel MCP server exposes your account's objects as MCP resources. Each resource URI lists all items or returns a specific one. + +| Resource | Description | +|----------|-------------| +| `browsers://` | Access browser sessions (list all or get a specific session). | +| `browser_pools://` | Access browser pools (list all or get a specific pool). | +| `profiles://` | Access browser profiles (list all or get a specific profile). | +| `apps://` | Access deployed apps (list all or get a specific app). | diff --git a/reference/mcp-server/tools/computer-action.mdx b/reference/mcp-server/tools/computer-action.mdx new file mode 100644 index 0000000..9f73010 --- /dev/null +++ b/reference/mcp-server/tools/computer-action.mdx @@ -0,0 +1,45 @@ +--- +title: "computer_action" +description: "Mouse, keyboard, and screenshot controls for browser sessions" +--- + +Execute computer actions on a browser session. Pass a single action for simple operations, or pass multiple actions to batch them into one request for lower latency. + +Always include a `screenshot` as the last action so you can see the result. `screenshot` and `get_mouse_position` return data, so they must come last. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `session_id` | Browser session ID. Required. | +| `actions` | Ordered list of actions to perform. Required. | + +## Action types + +| Type | Description | +|------|-------------| +| `click_mouse` | Click at `x`, `y`. Supports `button`, `click_type`, `num_clicks`, `hold_keys`. | +| `move_mouse` | Move the cursor to `x`, `y`. | +| `type_text` | Type `text`, with optional inter-key `delay`. | +| `press_key` | Press `keys` (X11 keysym names or combos like `Ctrl+t`, `Return`). | +| `scroll` | Scroll at `x`, `y` by `delta_x`/`delta_y` (positive = right/down). | +| `drag_mouse` | Drag along a `path` of `[x, y]` points. | +| `set_cursor` | Show or hide the cursor (`hidden`). | +| `sleep` | Wait `duration_ms` between steps when the page needs time to react. | +| `screenshot` | Capture the page, optionally limited to a `region`. | +| `get_mouse_position` | Return the current cursor position. | + +## Example + +```json +{ + "session_id": "browser_abc123", + "actions": [ + { "type": "click_mouse", "click_mouse": { "x": 420, "y": 300 } }, + { "type": "type_text", "type_text": { "text": "kernel browsers" } }, + { "type": "press_key", "press_key": { "keys": ["Return"] } }, + { "type": "sleep", "sleep": { "duration_ms": 1000 } }, + { "type": "screenshot" } + ] +} +``` diff --git a/reference/mcp-server/tools/exec-command.mdx b/reference/mcp-server/tools/exec-command.mdx new file mode 100644 index 0000000..c2138c1 --- /dev/null +++ b/reference/mcp-server/tools/exec-command.mdx @@ -0,0 +1,27 @@ +--- +title: "exec_command" +description: "Run shell commands inside a browser VM" +--- + +Execute a command synchronously inside a browser VM. Returns decoded stdout, stderr, and the exit code. The `command` field is the executable; pass its arguments in `args`. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `session_id` | Browser session ID. Required. | +| `command` | Executable to run (e.g., `cat`, `ls`, `curl`). Required. | +| `args` | Arguments to pass to the command. | +| `cwd` | Working directory (absolute path). | +| `as_root` | Run with root privileges. | +| `timeout_sec` | Max execution time in seconds. | + +## Example + +```json +{ + "session_id": "browser_abc123", + "command": "curl", + "args": ["-I", "https://example.com"] +} +``` diff --git a/reference/mcp-server/tools/execute-playwright-code.mdx b/reference/mcp-server/tools/execute-playwright-code.mdx new file mode 100644 index 0000000..7152515 --- /dev/null +++ b/reference/mcp-server/tools/execute-playwright-code.mdx @@ -0,0 +1,33 @@ +--- +title: "execute_playwright_code" +description: "Run Playwright/TypeScript code against a browser session" +--- + +Execute Playwright/TypeScript automation code against a Kernel browser session. If `session_id` is provided, uses that existing browser; otherwise creates a new one. Returns the result with a video replay URL, and auto-cleans up browsers it creates. + +Use `computer_action` with the `screenshot` action instead of `page.screenshot()` in your code. For a comprehensive page state snapshot, use `await page._snapshotForAI()`. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `code` | Playwright/TypeScript code with a `page` object in scope. Required. | +| `session_id` | Existing browser session ID. If omitted, a new browser is created and cleaned up after execution. | + +## Example + +```json +{ + "code": "await page.goto('https://example.com'); return await page.title();" +} +``` + +Returns: + +```json +{ + "success": true, + "result": "Example Domain", + "replay_url": "https://..." +} +``` diff --git a/reference/mcp-server/tools/manage-apps.mdx b/reference/mcp-server/tools/manage-apps.mdx new file mode 100644 index 0000000..7e0c082 --- /dev/null +++ b/reference/mcp-server/tools/manage-apps.mdx @@ -0,0 +1,41 @@ +--- +title: "manage_apps" +description: "List apps, invoke actions, and check deployments and invocations" +--- + +Manage Kernel apps, deployments, and invocations. + +## Actions + +| Action | Description | +|--------|-------------| +| `list_apps` | Discover apps. | +| `invoke` | Execute an app action. | +| `get_deployment` | Retrieve a deployment by ID. | +| `list_deployments` | Check deployment status. | +| `get_invocation` | Check action results. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `app_name` | (list_apps, invoke, list_deployments) App name filter or target. | +| `action_name` | (invoke) Action to execute within the app. | +| `payload` | (invoke) JSON string with action parameters. | +| `version` | (list_apps, invoke) App version filter. Defaults to `latest` for invoke. | +| `deployment_id` | (get_deployment) Deployment ID to retrieve. | +| `invocation_id` | (get_invocation) Invocation ID to retrieve. | +| `limit` | (list_apps, list_deployments) Max results. Default 50. | +| `offset` | (list_apps, list_deployments) Pagination offset. Default 0. | + +## Example + +```json +{ + "action": "invoke", + "app_name": "web-scraper", + "action_name": "scrape", + "payload": "{\"url\": \"https://reddit.com\"}" +} +``` diff --git a/reference/mcp-server/tools/manage-browser-pools.mdx b/reference/mcp-server/tools/manage-browser-pools.mdx new file mode 100644 index 0000000..b794b99 --- /dev/null +++ b/reference/mcp-server/tools/manage-browser-pools.mdx @@ -0,0 +1,48 @@ +--- +title: "manage_browser_pools" +description: "Create and manage pools of pre-warmed browsers" +--- + +Manage pools of pre-warmed browser instances for fast acquisition. + +## Actions + +| Action | Description | +|--------|-------------| +| `create` | Set up a pool. | +| `list` | List pools. | +| `get` | Inspect a specific pool. | +| `acquire` | Get a browser from a pool. | +| `release` | Return a browser to a pool. | +| `flush` | Destroy idle browsers in a pool. | +| `delete` | Remove a pool. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform. Required. | +| `id_or_name` | Pool ID or name. Required for `get`, `delete`, `flush`, `acquire`, and `release`. | +| `name` | (create) Unique pool name. | +| `size` | (create) Number of browsers to maintain in the pool. | +| `fill_rate_per_minute` | (create) Pool fill rate percentage per minute. Default 10%. | +| `headless` | (create) Headless mode for pool browsers. | +| `stealth` | (create) Stealth mode for pool browsers. | +| `profile_name` | (create) Profile to load into pool browsers. | +| `proxy_id` | (create) Proxy for pool browsers. | +| `timeout_seconds` | (create) Idle timeout for acquired browsers. Default 600. | +| `acquire_timeout_seconds` | (acquire) Max seconds to wait for a browser. | +| `session_id` | (release) Session ID of the browser to release. | +| `reuse` | (release) Reuse the browser instance or recreate it. Default true. | +| `force` | (delete) Force delete even if browsers are leased. | + +## Example + +```json +{ + "action": "create", + "name": "scrape-pool", + "size": 5, + "stealth": true +} +``` diff --git a/reference/mcp-server/tools/manage-browsers.mdx b/reference/mcp-server/tools/manage-browsers.mdx new file mode 100644 index 0000000..5cf3816 --- /dev/null +++ b/reference/mcp-server/tools/manage-browsers.mdx @@ -0,0 +1,48 @@ +--- +title: "manage_browsers" +description: "Create, list, get, and delete browser sessions" +--- + +Manage browser sessions on the Kernel platform. Created browsers run in isolated VMs and support headless/stealth modes, profiles, proxies, viewports, extensions, and SSH tunneling. + +## Actions + +| Action | Description | +|--------|-------------| +| `create` | Launch a new browser session. | +| `list` | List existing sessions. | +| `get` | Retrieve details about a specific session. | +| `delete` | Terminate a session. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform: `create`, `list`, `get`, or `delete`. Required. | +| `session_id` | Browser session ID. Required for `get` and `delete`. | +| `headless` | (create) Launch without GUI. Faster but no live view. | +| `stealth` | (create) Avoid bot detection. Recommended for scraping. | +| `kiosk_mode` | (create) Hide address bar/tabs in live view. | +| `profile_id` / `profile_name` | (create) Profile to load saved cookies/logins. Use one, not both. | +| `save_profile_changes` | (create) Save session changes back to the profile on close. | +| `proxy_id` | (create) Proxy ID for traffic routing. | +| `extension_id` / `extension_name` | (create) Extension to load. | +| `viewport_width` / `viewport_height` | (create) Window size in pixels. Must be set together. | +| `viewport_refresh_rate` | (create) Display refresh rate in Hz. | +| `timeout_seconds` | (create) Inactivity timeout in seconds (max 259200 = 72h). Default 60. | +| `local_forward` | (create) SSH local forwarding (`localport:host:remoteport`). | +| `remote_forward` | (create) SSH remote forwarding (`remoteport:host:localport`). Use to expose a local dev server to the browser. | +| `status` | (list) Filter by status: `active`, `deleted`, or `all`. Default `active`. | +| `limit` | (list) Max results per page. Default 50. | +| `offset` | (list) Pagination offset. Default 0. | + +## Example + +```json +{ + "action": "create", + "stealth": true, + "proxy_id": "proxy_residential_us", + "timeout_seconds": 3600 +} +``` diff --git a/reference/mcp-server/tools/manage-extensions.mdx b/reference/mcp-server/tools/manage-extensions.mdx new file mode 100644 index 0000000..b2a27e8 --- /dev/null +++ b/reference/mcp-server/tools/manage-extensions.mdx @@ -0,0 +1,29 @@ +--- +title: "manage_extensions" +description: "List and delete uploaded browser extensions" +--- + +Manage browser extensions uploaded to your organization. + +## Actions + +| Action | Description | +|--------|-------------| +| `list` | List all extensions. | +| `delete` | Remove an extension. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform: `list` or `delete`. Required. | +| `id_or_name` | (delete) Extension ID or name to delete. | + +## Example + +```json +{ + "action": "delete", + "id_or_name": "my-extension" +} +``` diff --git a/reference/mcp-server/tools/manage-profiles.mdx b/reference/mcp-server/tools/manage-profiles.mdx new file mode 100644 index 0000000..ab8cbd9 --- /dev/null +++ b/reference/mcp-server/tools/manage-profiles.mdx @@ -0,0 +1,32 @@ +--- +title: "manage_profiles" +description: "Set up, list, and delete browser profiles" +--- + +Manage browser profiles that persist cookies, logins, and session data across browser sessions. + +## Actions + +| Action | Description | +|--------|-------------| +| `setup` | Create or update a profile with a guided live browser session. | +| `list` | List all profiles. | +| `delete` | Remove a profile. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform: `setup`, `list`, or `delete`. Required. | +| `profile_name` | (setup, delete) Profile name. For setup: 1–255 chars. For delete: name of the profile to remove. | +| `profile_id` | (delete) Profile ID to delete. Alternative to `profile_name`. | +| `update_existing` | (setup) If true, update an existing profile. Default false. | + +## Example + +```json +{ + "action": "setup", + "profile_name": "work-accounts" +} +``` diff --git a/reference/mcp-server/tools/manage-proxies.mdx b/reference/mcp-server/tools/manage-proxies.mdx new file mode 100644 index 0000000..1392854 --- /dev/null +++ b/reference/mcp-server/tools/manage-proxies.mdx @@ -0,0 +1,41 @@ +--- +title: "manage_proxies" +description: "Create, list, and delete proxy configurations" +--- + +Manage proxy configurations for routing browser traffic. Proxy quality for bot detection avoidance, best to worst: mobile > residential > ISP > datacenter. + +## Actions + +| Action | Description | +|--------|-------------| +| `create` | Add a proxy. | +| `list` | List all proxies. | +| `delete` | Remove a proxy. | + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `action` | Operation to perform: `create`, `list`, or `delete`. Required. | +| `type` | (create) Proxy type: `datacenter`, `isp`, `residential`, `mobile`, or `custom`. | +| `name` | (create) Readable name for the proxy. | +| `country` | (create) ISO 3166 country code (e.g., `US`). | +| `state` | (create) Two-letter state code. | +| `city` | (create) City name without spaces (e.g., `sanfrancisco`). Requires `country`. | +| `custom_host` | (create, custom type) Proxy host address. | +| `custom_port` | (create, custom type) Proxy port. | +| `custom_username` | (create, custom type) Auth username. | +| `custom_password` | (create, custom type) Auth password. | +| `proxy_id` | (delete) Proxy ID to delete. | + +## Example + +```json +{ + "action": "create", + "type": "residential", + "name": "us-residential", + "country": "US" +} +``` diff --git a/reference/mcp-server/tools/search-docs.mdx b/reference/mcp-server/tools/search-docs.mdx new file mode 100644 index 0000000..91789e4 --- /dev/null +++ b/reference/mcp-server/tools/search-docs.mdx @@ -0,0 +1,20 @@ +--- +title: "search_docs" +description: "Search Kernel platform documentation and guides" +--- + +Search Kernel platform documentation for guides, tutorials, and API references. Use it when you need to understand how Kernel features work or to troubleshoot issues. + +## Parameters + +| Parameter | Description | +|-----------|-------------| +| `query` | Natural language search query (e.g., "how to deploy an app", "browser automation examples"). Required. | + +## Example + +```json +{ + "query": "how to set up a browser profile for authentication" +} +``` diff --git a/reference/mcp-server/transports.mdx b/reference/mcp-server/transports.mdx new file mode 100644 index 0000000..ec3a83f --- /dev/null +++ b/reference/mcp-server/transports.mdx @@ -0,0 +1,21 @@ +--- +title: "Transports" +description: "Connect to the Kernel MCP server over streamable HTTP or stdio" +--- + +The Kernel MCP server is reachable at a single endpoint over two transports. + +- **Streamable HTTP (recommended):** `https://mcp.onkernel.com/mcp` +- **stdio via `mcp-remote`** (for clients without remote MCP support): + + ```bash + npx -y mcp-remote https://mcp.onkernel.com/mcp + ``` + +Use the streamable HTTP endpoint where supported for increased reliability. If your client doesn't support remote MCP, use `mcp-remote` over stdio. + + +**Quick setup:** Use the Kernel CLI to automatically configure MCP for your tool: `kernel mcp install --target `. See the [CLI MCP documentation](/reference/cli/mcp) for details. + + +Once you've chosen a transport, [connect your client](/reference/mcp-server/clients/claude) and set up [authentication](/reference/mcp-server/authentication). diff --git a/reference/mcp-server/troubleshooting.mdx b/reference/mcp-server/troubleshooting.mdx new file mode 100644 index 0000000..61b5702 --- /dev/null +++ b/reference/mcp-server/troubleshooting.mdx @@ -0,0 +1,9 @@ +--- +title: "Troubleshooting" +description: "Fix connection and authentication issues with the Kernel MCP server" +--- + +- **Cursor clean reset:** ⌘/Ctrl Shift P → run `Cursor: Clear All MCP Tokens` (resets all MCP servers and auth; re-enable Kernel and re-authenticate). +- **Clear saved auth and retry:** `rm -rf ~/.mcp-auth` +- **Node.js version:** Ensure a recent Node.js version when using `npx mcp-remote`. +- **Strict networks:** If behind strict networks, try stdio via `mcp-remote`, or explicitly set the transport your client supports.