Document named MCP OAuth clients and cache migration

reference/mcp-server/clients/antigravity.mdx

@@ -15,9 +15,11 @@ 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:
+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
 {
@@ -28,9 +30,11 @@ 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\"}"
-      ]
+      ],
+      "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-antigravity"}
     }
   }
 }
@@ -40,6 +44,10 @@ 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.
+
+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
 
 Go to **Settings → Customizations**, scroll to **Installed MCP Servers**, and click the reload button.

reference/mcp-server/clients/claude.mdx

@@ -15,6 +15,14 @@ Kernel is available as an [official connector](https://claude.ai/directory/kerne
 
 <Info>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.</Info>
 
+## Configure Claude Desktop with mcp-remote
+
+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. Use `46093` for Claude Desktop. If you customize it, choose an unused port that no other client uses.
+
+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
 
 **Using Kernel CLI (recommended):**

reference/mcp-server/clients/goose.mdx

@@ -9,10 +9,12 @@ 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.
 
-**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.
+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=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,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 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.
 
@@ -36,6 +39,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 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`
+
+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.

reference/mcp-server/clients/windsurf.mdx

@@ -9,21 +9,28 @@ 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.
 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", "46095", "--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.
+
+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.

reference/mcp-server/clients/zed.mdx

@@ -9,19 +9,25 @@ 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.
-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", "46097", "--static-oauth-client-metadata", "{\"client_name\":\"Zed\"}"],
+      "env": {"MCP_REMOTE_CONFIG_DIR": "/home/user/.mcp-auth/kernel-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.