docs(mcp): add headless and ssh guidance with API key authentication

.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.

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>"
+```

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.

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>
   );