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/3] 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/3] 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`. From 0704e44f064366d82e6977cd8b6e9112cf86d622 Mon Sep 17 00:00:00 2001 From: Sayan- <1415138+Sayan-@users.noreply.github.com> Date: Thu, 24 Sep 2026 20:12:52 +0000 Subject: [PATCH 3/3] docs(mcp): clarify manual OAuth setup before CLI defaults --- reference/mcp-server/clients/antigravity.mdx | 4 +++- reference/mcp-server/clients/claude.mdx | 8 ++++---- reference/mcp-server/clients/goose.mdx | 4 ++-- reference/mcp-server/clients/windsurf.mdx | 4 +++- reference/mcp-server/clients/zed.mdx | 4 +++- 5 files changed, 15 insertions(+), 9 deletions(-) diff --git a/reference/mcp-server/clients/antigravity.mdx b/reference/mcp-server/clients/antigravity.mdx index c80ccdb1..0c5ea95d 100644 --- a/reference/mcp-server/clients/antigravity.mdx +++ b/reference/mcp-server/clients/antigravity.mdx @@ -15,6 +15,8 @@ Run the following command: kernel mcp install --target antigravity ``` +Check the installed Kernel entry against the example below. Add any missing callback port or cache directory before authorizing. + ## 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. This Linux example uses a cache directory under `/home/user`; change it to an absolute directory in your home directory: @@ -44,7 +46,7 @@ If the entry previously used `serverUrl`, remove that key. Reload the window to 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. +If you already set `MCP_REMOTE_CONFIG_DIR`, 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. Authorize again after updating the config. ## Connect diff --git a/reference/mcp-server/clients/claude.mdx b/reference/mcp-server/clients/claude.mdx index 1e266c98..f67f934a 100644 --- a/reference/mcp-server/clients/claude.mdx +++ b/reference/mcp-server/clients/claude.mdx @@ -15,13 +15,13 @@ 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 +## Configure Claude Desktop with mcp-remote -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. +If you connected Claude Desktop with `kernel mcp install --target claude`, update the Kernel server entry with the settings below, then authorize again. Give Claude Desktop its own `mcp-remote` auth cache so it doesn't reuse another client's registration. -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. +Each client needs a separate OAuth callback port as well as a separate cache to authorize while other clients are running. Use `46093` for Claude Desktop. 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. +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 02d3d381..88438d47 100644 --- a/reference/mcp-server/clients/goose.mdx +++ b/reference/mcp-server/clients/goose.mdx @@ -9,7 +9,7 @@ description: "Connect Goose Desktop and Goose CLI to the Kernel MCP server" kernel mcp install --target goose ``` -The command will display the YAML configuration to add to your Goose config file. +The command displays YAML configuration for your Goose config file. Compare it with the settings below and add any missing callback port, client metadata, or cache directory before pasting it. 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. @@ -44,4 +44,4 @@ 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` -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. +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. diff --git a/reference/mcp-server/clients/windsurf.mdx b/reference/mcp-server/clients/windsurf.mdx index c97b670b..99129ccf 100644 --- a/reference/mcp-server/clients/windsurf.mdx +++ b/reference/mcp-server/clients/windsurf.mdx @@ -9,6 +9,8 @@ description: "Connect Windsurf to the Kernel MCP server" kernel mcp install --target windsurf ``` +Compare the installed Kernel entry with the manual example below. Add any missing OAuth metadata, callback port, or cache directory before authorizing. + **Manual setup:** 1. Press **⌘/Ctrl ,** to open settings. @@ -31,4 +33,4 @@ kernel mcp install --target windsurf 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`. +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. diff --git a/reference/mcp-server/clients/zed.mdx b/reference/mcp-server/clients/zed.mdx index 6b5cacef..c5ff4390 100644 --- a/reference/mcp-server/clients/zed.mdx +++ b/reference/mcp-server/clients/zed.mdx @@ -9,6 +9,8 @@ description: "Connect Zed to the Kernel MCP server" kernel mcp install --target zed ``` +Compare the installed Kernel entry with the manual example below. Add any missing OAuth metadata, callback port, or cache directory before authorizing. + **Manual setup:** 1. Press **⌘/Ctrl ,** to open settings. @@ -28,4 +30,4 @@ kernel mcp install --target zed 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`. +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.