From 3d241ae0aa1ef41fedb15b87e4e47b9910b59a25 Mon Sep 17 00:00:00 2001
From: Aditya kumar singh <143548997+Adityakk9031@users.noreply.github.com>
Date: Sat, 3 Oct 2026 17:12:49 +0530
Subject: [PATCH] feat(react): add headless and ssh api key guidance to mcp
 connect card

---
 .changeset/headless-ssh-mcp-auth-api-keys.md  |  5 +++
 apps/docs/hosted/cloud.mdx                    | 38 +++++++++++++++++++
 apps/docs/mcp-proxy.mdx                       |  3 +-
 .../react/src/components/mcp-install-card.tsx | 16 ++++++++
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 .changeset/headless-ssh-mcp-auth-api-keys.md

diff --git a/.changeset/headless-ssh-mcp-auth-api-keys.md b/.changeset/headless-ssh-mcp-auth-api-keys.md
new file mode 100644
index 0000000000..6e52f6a4c0
--- /dev/null
+++ b/.changeset/headless-ssh-mcp-auth-api-keys.md
@@ -0,0 +1,5 @@
+---
+"@executor-js/react": patch
+---
+
+Add headless and remote SSH environment API key authentication guidance to the MCP connect card to prevent browser OAuth loopback redirects and token timeout issues.
diff --git a/apps/docs/hosted/cloud.mdx b/apps/docs/hosted/cloud.mdx
index 15a6df662e..29b15bd949 100644
--- a/apps/docs/hosted/cloud.mdx
+++ b/apps/docs/hosted/cloud.mdx
@@ -12,3 +12,41 @@ Sign in at [executor.sh](https://executor.sh), then add your first
 and point your agents at the hosted [MCP endpoint](/mcp-proxy). It is the easiest way
 to share one tool catalog across every agent you use, including cloud agents like
 ChatGPT.
+
+## Authentication Methods
+
+Executor Cloud supports two authentication methods for connecting MCP clients:
+
+### 1. Browser OAuth
+
+Interactive desktop clients (Claude Code, Cursor) automatically initiate browser OAuth via RFC 9728 discovery when connecting to your endpoint (`https://v2.executor.sh/<org-slug>/mcp`). The browser logs in through AuthKit and redirects back to the client.
+
+### 2. API Keys (Recommended for SSH & Headless Environments)
+
+If you are running agents in remote SSH sessions, Docker containers, or CI/CD pipelines, browser OAuth can be difficult because the callback attempts to redirect to a loopback `http://localhost` address on the remote host. Additionally, some clients do not support automatic refresh-token rotation when OAuth access tokens expire.
+
+To keep remote agents connected permanently without timeouts:
+
+1. Navigate to **Settings > API keys** (or `/api-keys`) in the Executor Cloud console.
+2. Create an API key.
+3. Pass the key in the `Authorization` header when connecting:
+
+```bash
+npx add-mcp https://v2.executor.sh/<org-slug>/mcp --transport http --name executor --header "Authorization: Bearer <your-api-key>"
+```
+
+#### Codex CLI Configuration
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.executor]
+url = "https://v2.executor.sh/<org-slug>/mcp"
+http_headers = { "Authorization" = "Bearer <your-api-key>" }
+```
+
+Or via the command line:
+
+```bash
+codex mcp add executor https://v2.executor.sh/<org-slug>/mcp --header "Authorization: Bearer <your-api-key>"
+```
diff --git a/apps/docs/mcp-proxy.mdx b/apps/docs/mcp-proxy.mdx
index 1b49e1cb58..7f741da7d2 100644
--- a/apps/docs/mcp-proxy.mdx
+++ b/apps/docs/mcp-proxy.mdx
@@ -52,7 +52,8 @@ Executor:
 
 - **Local:** see [CLI](/local/cli) for `executor mcp` and the `add-mcp` command.
 - **Hosted:** see [Executor Cloud](/hosted/cloud), or self-host on
-  [Docker](/hosted/docker).
+  [Docker](/hosted/docker). For remote/SSH environments or long-running daemons,
+  use an API key with `--header "Authorization: Bearer <token>"` to bypass browser redirects.
 
 Once a client is connected, every integration you add to Executor appears in that
 agent automatically.
diff --git a/packages/react/src/components/mcp-install-card.tsx b/packages/react/src/components/mcp-install-card.tsx
index eac93d9b1f..a721e629af 100644
--- a/packages/react/src/components/mcp-install-card.tsx
+++ b/packages/react/src/components/mcp-install-card.tsx
@@ -395,6 +395,22 @@ export function McpInstallCard(props: { className?: string }) {
             )}
           </NativeSelect>
         </div>
+        {mode === "http" && (
+          <div className="mt-2 flex flex-col gap-2 rounded-md border border-border bg-muted/25 p-3">
+            <div className="min-w-0">
+              <div className="text-xs font-medium text-foreground">
+                Headless or SSH environments
+              </div>
+              <div className="mt-0.5 text-xs leading-5 text-muted-foreground">
+                To connect from remote SSH sessions or scripts without browser OAuth redirects or
+                token timeouts, authenticate using an API key from Settings &gt; API keys:
+              </div>
+              <div className="mt-1 font-mono text-xs text-muted-foreground">
+                --header &apos;Authorization: Bearer &lt;api-key&gt;&apos;
+              </div>
+            </div>
+          </div>
+        )}
       </CollapsibleContent>
     </Collapsible>
   );