feat(mcp): add Codex client, GitHub Copilot alias, refine uninstall/doctor

- Add Codex MCP client backed by ~/.codex/config.toml (smol-toml + a
  makeTomlClient codec on the shared makeFileClient factory); uses Codex's
  native Streamable HTTP transport, no mcp-remote bridge
- Rename the VS Code client display to "GitHub Copilot"; accept
  `--client copilot` as an alias for `vscode` (same config)
- uninstall: prompt lists only clients that have the entry, nothing
  pre-checked (select-to-remove), and warns how to install instead of
  erroring when nothing is registered
- doctor: probe every distinct configured MCP URL (not just the first);
  lower the probe timeout to 5s
- resolveClients dedupes aliases/repeats; remove dead projectPath export

Author: rafa-thayto

.changeset/mcp-install.md

@@ -2,4 +2,4 @@
 "clerk": minor
 ---
 
-Add `clerk mcp install`, `list`, and `uninstall` to register the Clerk remote MCP server (`https://mcp.clerk.com/mcp`) in Claude Code, Cursor, VS Code, Windsurf, and Gemini. Entries are written to each client's user-global config (e.g. `~/.claude.json`, `~/.cursor/mcp.json`), so the server is available across every project regardless of the directory you run the CLI from. `clerk doctor` gains an MCP reachability check that probes the configured server via the MCP `initialize` handshake when an entry is installed. By default the commands target Clerk's hosted server, so `clerk mcp install` works with no flags. The URL resolves in order: `--url` > the `CLERK_MCP_URL` override (for local worker development) > the active env profile's new `mcpUrl` field > the hosted server.
+Add `clerk mcp install`, `list`, and `uninstall` to register the Clerk remote MCP server (`https://mcp.clerk.com/mcp`) in Claude Code, Cursor, GitHub Copilot (VS Code; `--client vscode` or `--client copilot`), Windsurf, Gemini, and Codex. Entries are written to each client's user-global config (e.g. `~/.claude.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`), so the server is available across every project regardless of the directory you run the CLI from. `clerk doctor` gains an MCP reachability check that probes the configured server via the MCP `initialize` handshake when an entry is installed. By default the commands target Clerk's hosted server, so `clerk mcp install` works with no flags. The URL resolves in order: `--url` > the `CLERK_MCP_URL` override (for local worker development) > the active env profile's new `mcpUrl` field > the hosted server.

bun.lock

@@ -26,6 +26,7 @@
     "external-editor": "^3.1.0",
     "magicast": "^0.5.3",
     "semver": "^7.8.1",
+    "smol-toml": "^1.6.1",
     "yaml": "^2.9.0"
   },
   "devDependencies": {

packages/cli-core/package.json

@@ -15,7 +15,10 @@ import { link } from "./commands/link/index.ts";
 import { unlink } from "./commands/unlink/index.ts";
 import { apps as appsHandlers } from "./commands/apps/index.ts";
 import { users as usersHandlers } from "./commands/users/index.ts";
-import { mcp as mcpHandlers, CLIENT_IDS as MCP_CLIENT_IDS } from "./commands/mcp/index.ts";
+import {
+  mcp as mcpHandlers,
+  CLIENT_ID_CHOICES as MCP_CLIENT_CHOICES,
+} from "./commands/mcp/index.ts";
 import { doctor } from "./commands/doctor/index.ts";
 import { switchEnv } from "./commands/switch-env/index.ts";
 import { openDashboard } from "./commands/open/index.ts";
@@ -485,7 +488,7 @@ export function createProgram() {
     .description("Register the Clerk remote MCP server in supported clients")
     .addOption(
       createOption("--client <id>", "MCP client to target (repeatable). Default: all detected.")
-        .choices([...MCP_CLIENT_IDS])
+        .choices([...MCP_CLIENT_CHOICES])
         .argParser(collectOptionValues)
         .default([] as string[]),
     )
@@ -522,7 +525,7 @@ export function createProgram() {
         "--client <id>",
         "MCP client to target (repeatable). Default in human mode: pick from installed; in agent mode: all clients.",
       )
-        .choices([...MCP_CLIENT_IDS])
+        .choices([...MCP_CLIENT_CHOICES])
         .argParser(collectOptionValues)
         .default([] as string[]),
     )

packages/cli-core/src/cli-program.ts

@@ -25,17 +25,17 @@ clerk doctor --fix       # Offer to auto-fix issues
 
 ## Checks
 
-| Check                 | Category       | What it verifies                                                                                                                    |
-| --------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| Authentication token  | Authentication | Credential store has a stored token                                                                                                 |
-| Token validity        | Authentication | Token is still valid (calls `/oauth/userinfo`)                                                                                      |
-| Project linkage       | Project        | Current directory is linked to a Clerk app                                                                                          |
-| Linked application    | Project        | Linked application ID is accessible via the API                                                                                     |
-| Instances             | Project        | Configured dev/prod instance IDs match the application's instances                                                                  |
-| Environment variables | Environment    | .env.local or .env has Clerk keys                                                                                                   |
-| CLI configuration     | Configuration  | CLI config file exists and parses                                                                                                   |
-| Shell completion      | Configuration  | Shell autocompletion is installed for the detected shell                                                                            |
-| MCP server            | Integration    | If a Clerk MCP entry is installed, the configured server answers the `initialize` handshake (skipped otherwise; warns, never fails) |
+| Check                 | Category       | What it verifies                                                                                                                               |
+| --------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| Authentication token  | Authentication | Credential store has a stored token                                                                                                            |
+| Token validity        | Authentication | Token is still valid (calls `/oauth/userinfo`)                                                                                                 |
+| Project linkage       | Project        | Current directory is linked to a Clerk app                                                                                                     |
+| Linked application    | Project        | Linked application ID is accessible via the API                                                                                                |
+| Instances             | Project        | Configured dev/prod instance IDs match the application's instances                                                                             |
+| Environment variables | Environment    | .env.local or .env has Clerk keys                                                                                                              |
+| CLI configuration     | Configuration  | CLI config file exists and parses                                                                                                              |
+| Shell completion      | Configuration  | Shell autocompletion is installed for the detected shell                                                                                       |
+| MCP server            | Integration    | If a Clerk MCP entry is installed, every distinct configured server answers the `initialize` handshake (skipped otherwise; warns, never fails) |
 
 ## Auto-Fix (`--fix`)
 

packages/cli-core/src/commands/doctor/README.md

@@ -7,11 +7,25 @@
  */
 
 import { collectEntries } from "../mcp/collect.ts";
-import { probeMcp } from "../mcp/probe.ts";
+import { probeMcp, type McpProbeResult } from "../mcp/probe.ts";
 import type { CheckResult } from "./types.ts";
 
 const NAME = "MCP server";
 
+type UrlProbe = { url: string; result: McpProbeResult };
+
+function describeReachable(probes: UrlProbe[]): string {
+  return probes
+    .map(({ url, result }) => (result.ok ? `${result.serverName} (${url})` : url))
+    .join(", ");
+}
+
+function describeFailure(result: McpProbeResult): string {
+  if (result.ok) return "unknown";
+  if (result.error !== undefined) return result.error;
+  return result.status !== undefined ? `HTTP ${result.status}` : "unknown";
+}
+
 export async function checkMcp(): Promise<CheckResult> {
   // Only meaningful if the user actually registered a Clerk MCP entry —
   // otherwise skip silently rather than probing a server they don't use.
@@ -20,19 +34,24 @@ export async function checkMcp(): Promise<CheckResult> {
     return { name: NAME, status: "pass", message: "Skipped (no Clerk MCP entry installed)" };
   }
 
-  const url = entries[0]!.url;
-  const result = await probeMcp(url);
-  if (result.ok) {
-    return { name: NAME, status: "pass", message: `Reachable — ${result.serverName} (${url})` };
+  // Clients can point at different URLs (e.g. local dev in one, hosted in
+  // another), so probe every distinct one — a healthy first entry must not mask
+  // a broken second.
+  const urls = [...new Set(entries.map((e) => e.url))];
+  const probes = await Promise.all(urls.map(async (url) => ({ url, result: await probeMcp(url) })));
+
+  const unreachable = probes.find(({ result }) => !result.ok);
+  if (!unreachable) {
+    return { name: NAME, status: "pass", message: `Reachable — ${describeReachable(probes)}` };
   }
 
-  const detail =
-    result.error ?? (result.status !== undefined ? `HTTP ${result.status}` : "unknown");
+  const subject =
+    probes.length === 1 ? "Configured MCP server is" : "One or more configured MCP servers are";
   return {
     name: NAME,
     status: "warn",
-    message: `Configured MCP server is not reachable (${url})`,
-    detail,
+    message: `${subject} not reachable (${unreachable.url})`,
+    detail: describeFailure(unreachable.result),
     remedy: "Verify the server is running, or re-run `clerk mcp install` if the URL changed.",
   };
 }

packages/cli-core/src/commands/doctor/check-mcp.ts

@@ -66,7 +66,7 @@ describe("createDoctorContext", () => {
       const p1 = ctx.getToken();
       const p2 = ctx.getToken();
 
-      expect(p1).toBe(p2); // Same promise reference
+      expect(p1).toBe(p2);
       expect(await p1).toBe("test_token");
       expect(mockGetToken).toHaveBeenCalledTimes(1);
     });

packages/cli-core/src/commands/doctor/context.test.ts

@@ -14,27 +14,34 @@ environment variable > the active environment profile's `mcpUrl` field
 (e.g. `http://localhost:8787/mcp`).
 
 No Clerk API endpoints are called. To verify the server is reachable, run
-`clerk doctor` — its MCP check performs the `initialize` handshake against the
-configured URL whenever a Clerk MCP entry is installed.
+`clerk doctor` — its MCP check performs the `initialize` handshake against each
+distinct configured URL whenever a Clerk MCP entry is installed.
 
 ## Supported clients
 
 All entries are written to each client's **user-global** config, so the server
 is available in every project (no per-project approval, no dependence on which
 directory you run the CLI from).
 
-| ID         | Client                   | Scope | Config file                             |
-| ---------- | ------------------------ | ----- | --------------------------------------- |
-| `claude`   | Claude Code              | user  | `~/.claude.json` (`mcpServers`)         |
-| `cursor`   | Cursor                   | user  | `~/.cursor/mcp.json`                    |
-| `vscode`   | VS Code (Copilot)        | user  | VS Code user `mcp.json` (per-OS, below) |
-| `windsurf` | Windsurf                 | user  | `~/.codeium/windsurf/mcp_config.json`   |
-| `gemini`   | Gemini Code Assist / CLI | user  | `~/.gemini/settings.json`               |
-
-VS Code's user config dir is OS-specific: `~/Library/Application Support/Code/User/mcp.json`
-(macOS), `%APPDATA%\Code\User\mcp.json` (Windows), `$XDG_CONFIG_HOME/Code/User/mcp.json`
+| ID                   | Client                   | Scope | Config file                             |
+| -------------------- | ------------------------ | ----- | --------------------------------------- |
+| `claude`             | Claude Code              | user  | `~/.claude.json` (`mcpServers`)         |
+| `cursor`             | Cursor                   | user  | `~/.cursor/mcp.json`                    |
+| `vscode` (`copilot`) | GitHub Copilot (VS Code) | user  | VS Code user `mcp.json` (per-OS, below) |
+| `windsurf`           | Windsurf                 | user  | `~/.codeium/windsurf/mcp_config.json`   |
+| `gemini`             | Gemini Code Assist / CLI | user  | `~/.gemini/settings.json`               |
+| `codex`              | Codex                    | user  | `~/.codex/config.toml` (`mcp_servers`)  |
+
+GitHub Copilot's MCP server lives in VS Code's config, so `--client copilot` and
+`--client vscode` are aliases for the same client. Its user config dir is
+OS-specific: `~/Library/Application Support/Code/User/mcp.json` (macOS),
+`%APPDATA%\Code\User\mcp.json` (Windows), `$XDG_CONFIG_HOME/Code/User/mcp.json`
 (Linux) — the file behind **MCP: Open User Configuration**.
 
+Codex is the one TOML-backed client; the entry uses Codex's native Streamable
+HTTP transport (`url = "…"` under `[mcp_servers.<name>]`), so it needs no
+`mcp-remote` bridge. Rewriting `config.toml` does not preserve comments.
+
 ## Subcommands
 
 ### `clerk mcp install`
@@ -68,17 +75,20 @@ named `clerk` or pointing at any `*.clerk.com` host).
 
 ### `clerk mcp uninstall`
 
-Remove the named entry. In human mode with no `--client`/`--all`, it prompts
-with a multiselect of the clients that **currently have the entry**, so you
-choose exactly which to remove from. `--all` removes from every client without
-prompting; agent mode targets all clients; `--client <id>` (repeatable) targets
-specific clients. Throws `mcp_not_installed` (exit code 1) when nothing matched.
-Removing the entry doesn't drop a live editor session, so (in human mode) it
-prints a next step to reload each affected editor.
+Remove the entry. In human mode with no `--client`/`--all`, it prompts with a
+multiselect of the clients that **currently have the entry**, all unchecked:
+check the clients to remove the entry from and leave the rest unchecked, so the
+default (nothing checked) removes nothing. `--all` removes from every client
+without prompting; agent mode targets all clients; `--client <id>` (repeatable)
+targets specific clients. When nothing matches, it prints a warm hint to run
+`clerk mcp install` (no error, exit 0). Removing the entry doesn't drop a live
+editor session, so (in human mode) it prints a next step to reload each affected
+editor.
 
 > **Reachability:** there is no `mcp doctor` subcommand. Server health is part
-> of `clerk doctor`, which probes the configured MCP URL via the `initialize`
-> handshake when an entry is installed (warns, does not fail, when unreachable).
+> of `clerk doctor`, which probes each distinct configured MCP URL via the
+> `initialize` handshake when an entry is installed (warns, does not fail, when
+> any is unreachable).
 
 ## Error codes
 
@@ -88,4 +98,3 @@ prints a next step to reload each affected editor.
 | `mcp_client_not_supported`  | `--client <id>` is not in the supported list.                   |
 | `mcp_client_config_invalid` | An existing client config file is malformed.                    |
 | `mcp_url_required`          | The provided `--url` is malformed or uses a non-http(s) scheme. |
-| `mcp_not_installed`         | `uninstall` removed nothing because no entry matched.           |

packages/cli-core/src/commands/mcp/README.md

@@ -111,4 +111,16 @@ describe("client config paths + encoded shapes (homedir redirected)", () => {
     expect(parsed.servers).toBeDefined();
     expect(parsed.mcpServers).toBeUndefined();
   });
+
+  test("`copilot` resolves to the same client as `vscode`", async () => {
+    const { resolveClients } = await import("../shared.ts");
+    expect(resolveClients(["copilot"])).toEqual([vscodeClient]);
+    expect(resolveClients(["copilot"])).toEqual(resolveClients(["vscode"]));
+  });
+
+  test("resolveClients dedupes an alias and its canonical id to one client", async () => {
+    const { resolveClients } = await import("../shared.ts");
+    expect(resolveClients(["copilot", "vscode"])).toEqual([vscodeClient]);
+    expect(resolveClients(["cursor", "cursor"])).toEqual([cursorClient]);
+  });
 });

packages/cli-core/src/commands/mcp/clients/clients.test.ts

@@ -0,0 +1,20 @@
+/**
+ * Writes to `~/.codex/config.toml` under the `[mcp_servers.<name>]` table.
+ * Codex supports Streamable HTTP MCP servers directly, so the descriptor is
+ * just `{ url }` — no `mcp-remote` stdio bridge (unlike Gemini).
+ */
+
+import { hasStringProp, makeTomlClient } from "./make-json-client.ts";
+import { pathExists, userPath } from "./paths.ts";
+
+export const codexClient = makeTomlClient({
+  id: "codex",
+  displayName: "Codex",
+  scope: "user",
+  activation: "Restart Codex; it opens a browser to sign in if the server requires it.",
+  topKey: "mcp_servers",
+  encode: (url) => ({ url }),
+  extractUrl: (d) => (hasStringProp(d, "url") ? d.url : undefined),
+  configPath: () => userPath(".codex", "config.toml"),
+  detect: () => pathExists(userPath(".codex")),
+});