From 6e9f293e9f8ea31124596ee3a0c071bc73c4ea49 Mon Sep 17 00:00:00 2001 From: Mason Williams Date: Fri, 29 Aug 2025 21:59:14 -0400 Subject: [PATCH 1/7] docs(mcp-server): rewrite and clarify setup guide --- reference/mcp-server.mdx | 149 ++++++++++++++++----------------------- 1 file changed, 61 insertions(+), 88 deletions(-) diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx index 357c95e..0e13737 100644 --- a/reference/mcp-server.mdx +++ b/reference/mcp-server.mdx @@ -3,78 +3,32 @@ title: "MCP Server" description: "Access Kernel's cloud-based browsers via MCP" --- -Our Model Context Protocol (MCP) server gives any compatible AI model or agent a single, secure endpoint for launching Chromium browsers, injecting context, evaluating JavaScript, and streaming DOM snapshots from Kernel's cloud platform. +Our Model Context Protocol (MCP) server lets any compatible AI model or agent launch Chromium browsers, inject context, evaluate JavaScript, and stream DOM snapshots from Kernel's cloud platform — via a single secure endpoint. -## First Time? Start Here! - -Ready to try Kernel but don't have a browser automation yet? Perfect! Here's how to get started: - -### Step 1: Install Kernel MCP Server - -Install the Kernel MCP server to your favorite MCP client using the [setup instructions](#setup-instructions) below. - -### Step 2: Ask Your AI Assistant for Help - -Once connected, simply ask in your MCP client chat: - -``` -"How do I get a Kernel sample app set up locally?" -``` +## Setup Instructions -Your AI assistant will use the `search_docs` tool to get you the latest quickstart instructions and guide you through setting up your first Kernel app! +### General (Transports) -### Step 3: Deploy & Test with MCP Tools +- 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` -After you have a sample app locally, ask your assistant: +Use the streamable HTTP endpoint where supported for increased reliability. If your client does not support remote MCP, use `mcp-remote` over stdio. -``` -"Deploy my sample app to Kernel" -``` +Kernel's server is a centrally hosted, authenticated remote MCP using OAuth 2.1 with dynamic client registration. -Then test it: - -``` -"Run my app and get the title from onkernel.com" -``` +## Connect in your client -## Available Tools -The server provides these tools for AI assistants: +### Claude -### Browser Automation -- `create_browser` - Launch a new browser session -- `get_browser` - Get browser session information -- `delete_browser` - Terminate a browser session -- `list_browsers` - List active browser sessions +#### Team & Enterprise (Claude.ai) -### App Management -- `deploy_app` - Deploy TypeScript or Python apps to Kernel -- `list_apps` - List apps in your Kernel organization -- `invoke_action` - Execute actions in Kernel apps -- `get_deployment` - Get deployment status and logs -- `list_deployments` - List all deployments -- `get_invocation` - Get action invocation details +1. Go to **Settings → Integrations → Add more**. +2. Enter: **Integration name:** `Kernel`, **Integration URL:** `https://mcp.onkernel.com/mcp`. +3. Start a chat, enable **Tools**, complete auth. -### Documentation & Search -- `search_docs` - Search Kernel platform documentation and guides +#### Free & Pro (Claude desktop) -## Setup Instructions - -Add the Kernel MCP server to your favorite MCP-compatible client using `https://mcp.onkernel.com/mcp`. - -## Claude - -### Team & Enterprise (Claude.ai) - -1. Navigate to **Settings** in the sidebar (web or desktop). -2. Scroll to **Integrations** and click **Add more**. -3. Fill in: - - **Integration name:** `Kernel` - - **Integration URL:** `https://mcp.onkernel.com/mcp` -4. Start a chat, enable **Tools**, and finish auth. - -### Free & Pro (Claude desktop) - -Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add: +Add to `~/Library/Application Support/Claude/claude_desktop_config.json` and restart Claude: ```json { @@ -89,24 +43,27 @@ Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add: Restart the Claude desktop app. -### Claude Code CLI +#### Claude Code CLI ```bash claude mcp add --transport http kernel https://mcp.onkernel.com/mcp -# then, inside the REPL: -/mcp # to run through auth +# Then in the REPL run once to authenticate: +/mcp ``` -## Cursor +### Cursor + +Install with one click or configure manually. -Click [here](cursor://anysphere.cursor-deeplink/mcp/install?name=kernel&config=eyJ1cmwiOiJodHRwczovL21jcC5vbmtlcm5lbC5jb20vbWNwIn0%3D) to install Kernel on Cursor in one click. +### One-click install -### Manual Setup +Click [here](cursor://anysphere.cursor-deeplink/mcp/install?name=kernel&config=eyJ1cmwiOiJodHRwczovL21jcC5vbmtlcm5lbC5jb20vbWNwIn0%3D). -1. Press **⌘/Ctrl Shift J** to open settings. -2. Click **Tools & Integrations**. -3. Click **New MCP server**. -4. Add the following configuration: +### Manual setup + +1. Press **⌘/Ctrl Shift J**. +2. Go to **Tools & Integrations → New MCP server**. +3. Add this configuration: ```json { @@ -118,9 +75,9 @@ Click [here](cursor://anysphere.cursor-deeplink/mcp/install?name=kernel&config=e } ``` -5. Save and the server will be available. +4. Save. The server will appear in Tools. -## Goose +### Goose 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. @@ -150,7 +107,7 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm - **Timeout**: `300` - **Description**: `Access Kernel's cloud-based browsers via MCP` -## Visual Studio Code +### Visual Studio Code ```json { @@ -169,13 +126,13 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm ```bash npx -y mcp-remote https://mcp.onkernel.com/mcp ``` -4. Name the server **Kernel** and press Enter. +4. Name the server **Kernel** → Enter. 5. Activate via **MCP: List Servers → Kernel → Start Server**. -## Windsurf +### Windsurf 1. Press **⌘/Ctrl ,** to open settings. -2. Navigate **Cascade → MCP servers** → **Add custom server**. +2. Go to **Cascade → MCP servers → Add custom server**. 3. Paste: ```json @@ -189,7 +146,7 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm } ``` -## Zed +### Zed Open `settings.json` and add: @@ -208,7 +165,7 @@ Open `settings.json` and add: } ``` -## Others +### Others Many other MCP-capable tools accept: @@ -218,17 +175,33 @@ Many other MCP-capable tools accept: Configure these values wherever the tool expects MCP server settings. -## Usage Examples +## Tools -### Deploy Local Apps to the Cloud +### Browser Automation +- `create_browser` - Launch a new browser session +- `get_browser` - Get browser session information +- `delete_browser` - Terminate a browser session +- `list_browsers` - List active browser sessions -``` -Human: I have a Playwright automation script open in my editor. Can you deploy it to Kernel? -Assistant: I'll read your local files and deploy them to Kernel for you. -[Uses deploy_app tool to upload your code and create a cloud deployment] -``` +### App Management +- `list_apps` - List apps in your Kernel organization +- `invoke_action` - Execute actions in Kernel apps +- `get_deployment` - Get deployment status and logs +- `list_deployments` - List all deployments +- `get_invocation` - Get action invocation details + +### Documentation & Search +- `search_docs` - Search Kernel platform documentation and guides + +## Troubleshooting + +- 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 +### Invoke apps from anywhere ``` Human: Run my web-scraper app to get data from reddit.com @@ -236,7 +209,7 @@ Assistant: I'll execute your web-scraper action with reddit.com as the target. [Uses invoke_action tool to run your deployed app in the cloud] ``` -### Create Persistent Browser Sessions +### Create persistent browser sessions ``` Human: Create a stealth browser session that I can reuse for testing login flows From 80c918c0e8790a01476fb808c5e14a1bd8b33d60 Mon Sep 17 00:00:00 2001 From: Mason Williams Date: Sun, 31 Aug 2025 08:33:07 -0400 Subject: [PATCH 2/7] docs: Add MCP token reset to troubleshooting --- reference/mcp-server.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/reference/mcp-server.mdx b/reference/mcp-server.mdx index 0e13737..15e9c59 100644 --- a/reference/mcp-server.mdx +++ b/reference/mcp-server.mdx @@ -195,6 +195,7 @@ Configure these values wherever the tool expects MCP server settings. ## 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 From 08335a8c63b42a6996bc7e6bbe9d95008724e0d9 Mon Sep 17 00:00:00 2001 From: Mason Williams Date: Mon, 1 Sep 2025 15:11:41 -0400 Subject: [PATCH 3/7] docs: Enhance CLI documentation with new authentication, browser, and app management sections --- docs.json | 5 +- reference/cli.mdx | 106 ++++---------- reference/cli/apps.mdx | 45 ++++++ reference/cli/auth.mdx | 20 +++ reference/cli/browsers.mdx | 277 +++++++++++++++++++++++++++++++++++++ 5 files changed, 373 insertions(+), 80 deletions(-) create mode 100644 reference/cli/apps.mdx create mode 100644 reference/cli/auth.mdx create mode 100644 reference/cli/browsers.mdx diff --git a/docs.json b/docs.json index c0d40d2..1e5d4a6 100644 --- a/docs.json +++ b/docs.json @@ -126,7 +126,10 @@ "tab": "CLI", "icon": "terminal", "pages": [ - "reference/cli" + "reference/cli", + "reference/cli/auth", + "reference/cli/browsers", + "reference/cli/apps" ] } ] diff --git a/reference/cli.mdx b/reference/cli.mdx index 8f032a0..de36ac6 100644 --- a/reference/cli.mdx +++ b/reference/cli.mdx @@ -6,8 +6,6 @@ The Kernel CLI helps you access and manage your Kernel resources. ## Installation -Install the Kernel CLI using your favorite package manager: - ```bash # Using brew brew install onkernel/tap/kernel @@ -19,94 +17,44 @@ pnpm install -g @onkernel/cli npm install -g @onkernel/cli ``` -## Authentication - -The Kernel CLI supports two authentication methods: - -### OAuth 2.0 (Recommended) - -The preferred method is OAuth 2.0 with PKCE, which provides secure browser-based authentication: +Verify installation: ```bash -kernel login +which kernel +kernel --version ``` -This opens your browser to complete the OAuth flow. Your tokens are securely stored in your system keychain (macOS/Windows) or a local file (Linux). - -### API Key + + + Login, logout, and check auth status. + + + Create, view, and manage Kernel browsers. + + + Deploy apps, invoke actions, and stream logs. + + -You can also authenticate using an API key: +## Quick Start ```bash -export KERNEL_API_KEY= -``` +# 1) Login +kernel login -## Verifying installation -After installation, verify that Kernel CLI was installed correctly: +# 2) Deploy your app +kernel deploy index.ts -```bash -which kernel +# 3) Invoke your app +kernel invoke my-app action-name --payload '{"key":"value"}' ``` ## Global Flags -| Flag | Description | -|------|-------------| -| `--version`, `-v` | Print the CLI version | -| `--no-color` | Disable color output | -| `--log-level ` | Set the log level (trace, debug, info, warn, error, fatal, print) | - -## Authentication Commands - -| Command | Description | -|---------|-------------| -| `kernel login [--force]` | Initiates OAuth 2.0 authentication flow via browser. Use `--force` to re-authenticate when already logged in | -| `kernel logout` | Clears stored authentication tokens and logs out | -| `kernel auth` | Displays current authentication status, user details, and token expiry. Use `--log-level debug` for detailed information including user ID and storage method | - -## Browser Management Commands - -| Command | Description | -|---------|-------------| -| `kernel browsers list` | List running or persistent browsers | -| `kernel browsers create` | Create a new browser session | -| | `--persistence-id ` | Unique identifier for browser session persistence. Optional. | -| | `--stealth` | Launch browser in stealth mode to avoid detection. Optional. | -| | `--headless` | Launch browser without GUI access. Optional. | -| `kernel browsers delete` | Delete a browser. Must specify either `--by-persistent-id` or `--by-id` | -| | `--by-persistent-id ` | Delete browser by persistent ID | -| | `--by-id ` | Delete browser by session ID | -| | `--yes`, `-y` | Skip confirmation prompt | -| `kernel browsers view` | Get the live view URL for a browser. Must specify either `--by-persistent-id` or `--by-id` | -| | `--by-persistent-id ` | View browser by persistent ID | -| | `--by-id ` | View browser by session ID | - -## App Management Commands - -| Command | Optional Flags | Description | -|---------|-------------| -------------| -| `kernel deploy ` | - | Deploys an app to Kernel from the current directory. | -| | `--version ` | Specify a version for the app (default: latest). Optional. | -| | `--force` | Allow overwrite of an existing version with the same name. Optional. | -| | `--env `, `-e` | Adds environment variables to the app. Expects the form `ENV_VAR=VAL` delimited by spaces. May be specified multiple times. Optional. | -| | `--env-file ` | Read environment variables from a file (.env format). May be specified multiple times. Optional. | -| `kernel invoke ` | - | Invokes a specific app action by its name. Generates an Invocation. | -| | `--version `, `-v` | Specify a version of the app to invoke (default: latest). Optional. | -| | `--payload `, `-p` | Includes the specified parameters. Expects a stringified JSON object. Optional. | -| | `--sync`, `-s` | Invoke synchronously (default false). A synchronous invocation opens a long-lived HTTP POST that times out after 60 seconds. Optional. | -| | `ctrl-c` | Terminates the running invocation in your CLI. Also destroys any associated browsers. | -| `kernel app list` | - | List deployed application versions. | -| | `--name ` | Filter by application name. Optional. | -| | `--version ` | Filter by version label. Optional. | -| `kernel app history ` | - | Show deployment history for an application. | -| `kernel logs ` | - | Prints the logs for the specified app. | -| | `--version ` | Specify a version of the app (default: latest). Optional. | -| | `--follow`, `-f` | Follow logs in real-time (stream continuously). Optional. | -| | `--since