From 120bf758683384bdd0a239d0a03c326e4af9838a Mon Sep 17 00:00:00 2001 From: Sayan- <1415138+Sayan-@users.noreply.github.com> Date: Wed, 23 Sep 2026 21:16:29 +0000 Subject: [PATCH 1/2] Document named MCP OAuth clients and cache migration --- reference/mcp-server/clients/antigravity.mdx | 7 +++++-- reference/mcp-server/clients/claude.mdx | 6 ++++++ reference/mcp-server/clients/goose.mdx | 12 ++++++++---- reference/mcp-server/clients/windsurf.mdx | 9 +++++++-- reference/mcp-server/clients/zed.mdx | 10 +++++++--- 5 files changed, 33 insertions(+), 11 deletions(-) diff --git a/reference/mcp-server/clients/antigravity.mdx b/reference/mcp-server/clients/antigravity.mdx index e534e770..3591961b 100644 --- a/reference/mcp-server/clients/antigravity.mdx +++ b/reference/mcp-server/clients/antigravity.mdx @@ -17,7 +17,7 @@ kernel mcp install --target antigravity ## Configure manually -Alternatively, open the agent side panel, click the ellipsis (**…**) menu, and select **MCP Servers**, then **Manage MCP Servers → View raw config**. Add Kernel to the `mcpServers` map in `mcp_config.json` — `~/.gemini/config/mcp_config.json` globally, or `.agents/mcp_config.json` for a single workspace: +Alternatively, open the agent side panel, click the ellipsis (**…**) menu, and select **MCP Servers**, then **Manage MCP Servers → View raw config**. Add Kernel to the `mcpServers` map in `mcp_config.json` — `~/.gemini/config/mcp_config.json` globally, or `.agents/mcp_config.json` for a single workspace. This Linux example uses a cache directory under `/home/user`; change it to an absolute directory in your home directory: ```json { @@ -30,7 +30,8 @@ Alternatively, open the agent side panel, click the ellipsis (**…**) menu, and "https://mcp.onkernel.com/mcp", "--static-oauth-client-metadata", "{\"client_name\":\"Antigravity\"}" - ] + ], + "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-antigravity"} } } } @@ -40,6 +41,8 @@ If the entry previously used `serverUrl`, remove that key. Reload the window to `--static-oauth-client-metadata` names the OAuth client. Without it, `mcp-remote` registers as **MCP CLI Proxy** and the Kernel consent screen asks you to trust that name instead of Antigravity. +The latest Kernel CLI gives Antigravity its own auth cache. After rerunning `kernel mcp install --target antigravity`, authorize again. If you already set `MCP_REMOTE_CONFIG_DIR`, the CLI preserves it; use a directory dedicated to Antigravity. To clear an old registration, close Antigravity and remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). This also signs out other clients using that cache. + ## Connect Go to **Settings → Customizations**, scroll to **Installed MCP Servers**, and click the reload button. diff --git a/reference/mcp-server/clients/claude.mdx b/reference/mcp-server/clients/claude.mdx index d67f98ea..69dd15e7 100644 --- a/reference/mcp-server/clients/claude.mdx +++ b/reference/mcp-server/clients/claude.mdx @@ -15,6 +15,12 @@ Kernel is available as an [official connector](https://claude.ai/directory/kerne 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. +## Existing Claude Desktop CLI setups + +If you connected Claude Desktop with `kernel mcp install --target claude`, rerun the command with the latest Kernel CLI and authorize again. By default, the updated config gives Claude Desktop its own `mcp-remote` auth cache, so the consent screen names Claude Desktop. If you already set `MCP_REMOTE_CONFIG_DIR` in the server's `env`, choose a separate directory for Claude Desktop yourself. + +For a manual `mcp-remote` setup, add `--static-oauth-client-metadata` followed by `{"client_name":"Claude Desktop"}` to the server's arguments, and set `MCP_REMOTE_CONFIG_DIR` in its `env` to an absolute directory dedicated to Claude Desktop. If the old registration still shows **MCP CLI Proxy**, close Claude Desktop, remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`), then reopen Claude Desktop and authorize again. This also signs out other clients using that cache. + ## Claude Code CLI **Using Kernel CLI (recommended):** diff --git a/reference/mcp-server/clients/goose.mdx b/reference/mcp-server/clients/goose.mdx index fbe8c95d..762cbe67 100644 --- a/reference/mcp-server/clients/goose.mdx +++ b/reference/mcp-server/clients/goose.mdx @@ -11,8 +11,8 @@ 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. +**Install link:** +Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fmcp.onkernel.com%2Fmcp&arg=--static-oauth-client-metadata&arg=%7B%22client_name%22%3A%22Goose%22%7D&env=MCP_REMOTE_CONFIG_DIR&timeout=300&id=kernel&name=Kernel&description=Access%20Kernel%27s%20cloud-based%20browsers%20via%20MCP) to add Kernel to Goose. When prompted, set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose so another client's cached registration can't be reused. ## Goose Desktop @@ -22,7 +22,8 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm - **Extension Name**: `Kernel` - **Type**: `STDIO` - **Description**: `Access Kernel's cloud-based browsers via MCP` - - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp` + - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp --static-oauth-client-metadata '{"client_name":"Goose"}'` + - **Environment variable**: Set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose. - **Timeout**: `300` 4. Click `Save Changes` button. @@ -36,6 +37,9 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm 3. Choose `Command-line Extension`. 4. Follow the prompts: - **Extension name**: `Kernel` - - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp` + - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp --static-oauth-client-metadata '{"client_name":"Goose"}'` + - **Environment variable**: Set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose. - **Timeout**: `300` - **Description**: `Access Kernel's cloud-based browsers via MCP` + +If you previously authorized Kernel and the consent screen still shows **MCP CLI Proxy**, close Goose, update the config above, then remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). Reopen Goose and authorize again. This also signs out other clients using that cache. The latest Kernel CLI prints a config with a separate Goose cache. diff --git a/reference/mcp-server/clients/windsurf.mdx b/reference/mcp-server/clients/windsurf.mdx index 01b5ea7f..b9cf3803 100644 --- a/reference/mcp-server/clients/windsurf.mdx +++ b/reference/mcp-server/clients/windsurf.mdx @@ -13,17 +13,22 @@ kernel mcp install --target windsurf 1. Press **⌘/Ctrl ,** to open settings. 2. Navigate **Cascade → MCP servers → View raw config**. -3. Paste: +3. Paste this Linux example, changing the cache path to an absolute directory in your home directory: ```json { "mcpServers": { "kernel": { "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp", "--static-oauth-client-metadata", "{\"client_name\":\"Windsurf\"}"], + "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-windsurf"} } } } ``` 4. On **Manage MCPs**, click **Refresh** to load Kernel MCP. + +`mcp-remote` reuses the first client's cached registration for the same server URL unless each client has a separate `MCP_REMOTE_CONFIG_DIR`. + +If you previously authorized Kernel and the consent screen still shows **MCP CLI Proxy**, close Windsurf, update the config above, then remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). Reopen Windsurf and authorize again. This also signs out other clients using that cache. Running `kernel mcp install --target windsurf` with the latest CLI configures a separate cache unless you already set `MCP_REMOTE_CONFIG_DIR` in the server's `env`. diff --git a/reference/mcp-server/clients/zed.mdx b/reference/mcp-server/clients/zed.mdx index 0335b8a9..35b27ae9 100644 --- a/reference/mcp-server/clients/zed.mdx +++ b/reference/mcp-server/clients/zed.mdx @@ -12,16 +12,20 @@ kernel mcp install --target zed **Manual setup:** 1. Press **⌘/Ctrl ,** to open settings. -2. Paste: +2. Paste this Linux example, changing the cache path to an absolute directory in your home directory: ```json { "context_servers": { "kernel": { - "source": "custom", "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp"] + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp", "--static-oauth-client-metadata", "{\"client_name\":\"Zed\"}"], + "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-zed"} } } } ``` + +`mcp-remote` reuses the first client's cached registration for the same server URL unless each client has a separate `MCP_REMOTE_CONFIG_DIR`. + +If you previously authorized Kernel and the consent screen still shows **MCP CLI Proxy**, close Zed, update the config above, then remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). Reopen Zed and authorize again. This also signs out other clients using that cache. Running `kernel mcp install --target zed` with the latest CLI configures a separate cache unless you already set `MCP_REMOTE_CONFIG_DIR` in the server's `env`. From b9013a6813da6f53aef6766c60c6777019ab55dd Mon Sep 17 00:00:00 2001 From: Sayan- <1415138+Sayan-@users.noreply.github.com> Date: Wed, 23 Sep 2026 21:36:34 +0000 Subject: [PATCH 2/2] Document separate MCP OAuth callback ports --- reference/mcp-server/clients/antigravity.mdx | 3 +++ reference/mcp-server/clients/claude.mdx | 4 +++- reference/mcp-server/clients/goose.mdx | 8 +++++--- reference/mcp-server/clients/windsurf.mdx | 4 ++-- reference/mcp-server/clients/zed.mdx | 4 ++-- 5 files changed, 15 insertions(+), 8 deletions(-) diff --git a/reference/mcp-server/clients/antigravity.mdx b/reference/mcp-server/clients/antigravity.mdx index 3591961b..c80ccdb1 100644 --- a/reference/mcp-server/clients/antigravity.mdx +++ b/reference/mcp-server/clients/antigravity.mdx @@ -28,6 +28,7 @@ Alternatively, open the agent side panel, click the ellipsis (**…**) menu, and "-y", "mcp-remote", "https://mcp.onkernel.com/mcp", + "46094", "--static-oauth-client-metadata", "{\"client_name\":\"Antigravity\"}" ], @@ -41,6 +42,8 @@ If the entry previously used `serverUrl`, remove that key. Reload the window to `--static-oauth-client-metadata` names the OAuth client. Without it, `mcp-remote` registers as **MCP CLI Proxy** and the Kernel consent screen asks you to trust that name instead of Antigravity. +The `46094` argument sets Antigravity's OAuth callback port. Each client needs a separate port as well as a separate cache to authorize while other clients are running. The CLI preserves an existing explicit port; if you customize it, choose an unused port that no other client uses. + The latest Kernel CLI gives Antigravity its own auth cache. After rerunning `kernel mcp install --target antigravity`, authorize again. If you already set `MCP_REMOTE_CONFIG_DIR`, the CLI preserves it; use a directory dedicated to Antigravity. To clear an old registration, close Antigravity and remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). This also signs out other clients using that cache. ## Connect diff --git a/reference/mcp-server/clients/claude.mdx b/reference/mcp-server/clients/claude.mdx index 69dd15e7..1e266c98 100644 --- a/reference/mcp-server/clients/claude.mdx +++ b/reference/mcp-server/clients/claude.mdx @@ -19,7 +19,9 @@ Kernel is available as an [official connector](https://claude.ai/directory/kerne If you connected Claude Desktop with `kernel mcp install --target claude`, rerun the command with the latest Kernel CLI and authorize again. By default, the updated config gives Claude Desktop its own `mcp-remote` auth cache, so the consent screen names Claude Desktop. If you already set `MCP_REMOTE_CONFIG_DIR` in the server's `env`, choose a separate directory for Claude Desktop yourself. -For a manual `mcp-remote` setup, add `--static-oauth-client-metadata` followed by `{"client_name":"Claude Desktop"}` to the server's arguments, and set `MCP_REMOTE_CONFIG_DIR` in its `env` to an absolute directory dedicated to Claude Desktop. If the old registration still shows **MCP CLI Proxy**, close Claude Desktop, remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`), then reopen Claude Desktop and authorize again. This also signs out other clients using that cache. +Each client needs a separate OAuth callback port as well as a separate cache to authorize while other clients are running. The CLI uses `46093` for Claude Desktop and preserves an existing explicit port. If you customize it, choose an unused port that no other client uses. + +For a manual `mcp-remote` setup, add `46093` immediately after the server URL, then add `--static-oauth-client-metadata` followed by `{"client_name":"Claude Desktop"}` to the server's arguments, and set `MCP_REMOTE_CONFIG_DIR` in its `env` to an absolute directory dedicated to Claude Desktop. If the old registration still shows **MCP CLI Proxy**, close Claude Desktop, remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`), then reopen Claude Desktop and authorize again. This also signs out other clients using that cache. ## Claude Code CLI diff --git a/reference/mcp-server/clients/goose.mdx b/reference/mcp-server/clients/goose.mdx index 762cbe67..02d3d381 100644 --- a/reference/mcp-server/clients/goose.mdx +++ b/reference/mcp-server/clients/goose.mdx @@ -11,8 +11,10 @@ kernel mcp install --target goose The command will display the YAML configuration to add to your Goose config file. +Each client needs a separate OAuth callback port as well as a separate cache to authorize while other clients are running. The config below uses `46096` for Goose. If you customize it, choose an unused port that no other client uses. + **Install link:** -Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fmcp.onkernel.com%2Fmcp&arg=--static-oauth-client-metadata&arg=%7B%22client_name%22%3A%22Goose%22%7D&env=MCP_REMOTE_CONFIG_DIR&timeout=300&id=kernel&name=Kernel&description=Access%20Kernel%27s%20cloud-based%20browsers%20via%20MCP) to add Kernel to Goose. When prompted, set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose so another client's cached registration can't be reused. +Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fmcp.onkernel.com%2Fmcp&arg=46096&arg=--static-oauth-client-metadata&arg=%7B%22client_name%22%3A%22Goose%22%7D&env=MCP_REMOTE_CONFIG_DIR&timeout=300&id=kernel&name=Kernel&description=Access%20Kernel%27s%20cloud-based%20browsers%20via%20MCP) to add Kernel to Goose. When prompted, set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose so another client's cached registration can't be reused. ## Goose Desktop @@ -22,7 +24,7 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm - **Extension Name**: `Kernel` - **Type**: `STDIO` - **Description**: `Access Kernel's cloud-based browsers via MCP` - - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp --static-oauth-client-metadata '{"client_name":"Goose"}'` + - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp 46096 --static-oauth-client-metadata '{"client_name":"Goose"}'` - **Environment variable**: Set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose. - **Timeout**: `300` 4. Click `Save Changes` button. @@ -37,7 +39,7 @@ Click [here](goose://extension?cmd=npx&arg=-y&arg=mcp-remote&arg=https%3A%2F%2Fm 3. Choose `Command-line Extension`. 4. Follow the prompts: - **Extension name**: `Kernel` - - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp --static-oauth-client-metadata '{"client_name":"Goose"}'` + - **Command**: `npx -y mcp-remote https://mcp.onkernel.com/mcp 46096 --static-oauth-client-metadata '{"client_name":"Goose"}'` - **Environment variable**: Set `MCP_REMOTE_CONFIG_DIR` to an absolute directory dedicated to Goose. - **Timeout**: `300` - **Description**: `Access Kernel's cloud-based browsers via MCP` diff --git a/reference/mcp-server/clients/windsurf.mdx b/reference/mcp-server/clients/windsurf.mdx index b9cf3803..c97b670b 100644 --- a/reference/mcp-server/clients/windsurf.mdx +++ b/reference/mcp-server/clients/windsurf.mdx @@ -20,7 +20,7 @@ kernel mcp install --target windsurf "mcpServers": { "kernel": { "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp", "--static-oauth-client-metadata", "{\"client_name\":\"Windsurf\"}"], + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp", "46095", "--static-oauth-client-metadata", "{\"client_name\":\"Windsurf\"}"], "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-windsurf"} } } @@ -29,6 +29,6 @@ kernel mcp install --target windsurf 4. On **Manage MCPs**, click **Refresh** to load Kernel MCP. -`mcp-remote` reuses the first client's cached registration for the same server URL unless each client has a separate `MCP_REMOTE_CONFIG_DIR`. +Each client needs a separate `MCP_REMOTE_CONFIG_DIR` and OAuth callback port. The `46095` argument sets Windsurf's port so it can authorize while other clients are running. The CLI preserves an existing explicit port; if you customize it, choose an unused port that no other client uses. If you previously authorized Kernel and the consent screen still shows **MCP CLI Proxy**, close Windsurf, update the config above, then remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). Reopen Windsurf and authorize again. This also signs out other clients using that cache. Running `kernel mcp install --target windsurf` with the latest CLI configures a separate cache unless you already set `MCP_REMOTE_CONFIG_DIR` in the server's `env`. diff --git a/reference/mcp-server/clients/zed.mdx b/reference/mcp-server/clients/zed.mdx index 35b27ae9..6b5cacef 100644 --- a/reference/mcp-server/clients/zed.mdx +++ b/reference/mcp-server/clients/zed.mdx @@ -19,13 +19,13 @@ kernel mcp install --target zed "context_servers": { "kernel": { "command": "npx", - "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp", "--static-oauth-client-metadata", "{\"client_name\":\"Zed\"}"], + "args": ["-y", "mcp-remote", "https://mcp.onkernel.com/mcp", "46097", "--static-oauth-client-metadata", "{\"client_name\":\"Zed\"}"], "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-zed"} } } } ``` -`mcp-remote` reuses the first client's cached registration for the same server URL unless each client has a separate `MCP_REMOTE_CONFIG_DIR`. +Each client needs a separate `MCP_REMOTE_CONFIG_DIR` and OAuth callback port. The `46097` argument sets Zed's port so it can authorize while other clients are running. The CLI preserves an existing explicit port; if you customize it, choose an unused port that no other client uses. If you previously authorized Kernel and the consent screen still shows **MCP CLI Proxy**, close Zed, update the config above, then remove the cache it used (`~/.mcp-auth/mcp-remote-v1/` by default, or `mcp-remote-v1/` under your custom `MCP_REMOTE_CONFIG_DIR`). Reopen Zed and authorize again. This also signs out other clients using that cache. Running `kernel mcp install --target zed` with the latest CLI configures a separate cache unless you already set `MCP_REMOTE_CONFIG_DIR` in the server's `env`.