feat(mcp): add clerk mcp install/list/uninstall commands

Register the Clerk remote MCP server (https://mcp.clerk.com/mcp) in Claude Code, Cursor, VS Code, Windsurf, and Gemini, each with a JSON/agent mode and human-mode 'next steps' guidance (reload + sign-in).

clerk doctor gains an MCP reachability check that probes the configured server via the MCP initialize handshake when an entry is installed (warns, never fails).

URL resolution: --url > CLERK_MCP_URL > active env profile mcpUrl.

Author: rafa-thayto

.changeset/mcp-install.md

@@ -0,0 +1,5 @@
+---
+"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. `clerk doctor` gains an MCP reachability check that probes the configured server via the MCP `initialize` handshake when an entry is installed. The URL comes from the active env profile's new `mcpUrl` field (or the `CLERK_MCP_URL` override) and can be overridden per-invocation with `--url` for local worker development.

README.md

@@ -41,6 +41,7 @@ Commands:
   open                                       Open Clerk resources in your browser
   apps                                       Manage your Clerk applications
   users       [options]                      Manage Clerk users
+  mcp                                        Manage the Clerk remote MCP server connection for AI editors and CLIs
   env                                        Manage environment variables
   config                                     Manage instance configuration
   enable                                     Enable Clerk features on the linked instance

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

@@ -15,6 +15,7 @@ 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 { doctor } from "./commands/doctor/index.ts";
 import { switchEnv } from "./commands/switch-env/index.ts";
 import { openDashboard } from "./commands/open/index.ts";
@@ -473,6 +474,75 @@ Give AI agents better Clerk context: install the Clerk skills
       }),
     );
 
+  const mcp = program
+    .command("mcp")
+    .description("Manage the Clerk remote MCP server connection for AI editors and CLIs")
+    .setExamples([
+      { command: "clerk mcp install", description: "Install into all detected MCP clients" },
+      { command: "clerk mcp install --client cursor", description: "Install into Cursor only" },
+      {
+        command: "clerk mcp install --url http://localhost:8787/mcp",
+        description: "Use a local worker URL",
+      },
+      { command: "clerk mcp list", description: "Show registered Clerk entries" },
+      { command: "clerk mcp uninstall", description: "Remove the Clerk entry from all clients" },
+    ]);
+
+  mcp
+    .command("install")
+    .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])
+        .argParser(collectOptionValues)
+        .default([] as string[]),
+    )
+    .option("--url <url>", "Override the MCP server URL (default: from active env profile)")
+    .option("--name <name>", 'Entry name in the client config (default: "clerk")')
+    .option("--all", "Install into every detected client without prompting")
+    .option("--force", "Overwrite an existing entry pointing at a different URL")
+    .option("--json", "Output as JSON")
+    .setExamples([
+      {
+        command: "clerk mcp install",
+        description: "Pick clients interactively (or all in agent mode)",
+      },
+      { command: "clerk mcp install --all", description: "Install into every detected client" },
+      {
+        command: "clerk mcp install --client cursor --client vscode",
+        description: "Install into specific clients",
+      },
+      {
+        command: "clerk mcp install --url http://localhost:8787/mcp",
+        description: "Target a local worker for development",
+      },
+    ])
+    .action((options) => mcpHandlers.install(options));
+
+  mcp
+    .command("list")
+    .description("List Clerk MCP entries registered across detected clients")
+    .option("--json", "Output as JSON")
+    .setExamples([{ command: "clerk mcp list", description: "List Clerk entries everywhere" }])
+    .action((options) => mcpHandlers.list(options));
+
+  mcp
+    .command("uninstall")
+    .description("Remove the Clerk MCP entry from supported clients")
+    .addOption(
+      createOption("--client <id>", "MCP client to target (repeatable). Default: all clients.")
+        .choices([...MCP_CLIENT_IDS])
+        .argParser(collectOptionValues)
+        .default([] as string[]),
+    )
+    .option("--name <name>", 'Entry name to remove (default: "clerk")')
+    .option("--json", "Output as JSON")
+    .setExamples([
+      { command: "clerk mcp uninstall", description: "Remove from every client" },
+      { command: "clerk mcp uninstall --client cursor", description: "Remove from Cursor only" },
+    ])
+    .action((options) => mcpHandlers.uninstall(options));
+
   const env = program
     .command("env")
     .description("Manage environment variables")

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

@@ -25,16 +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           |
+| 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) |
 
 ## Auto-Fix (`--fix`)
 

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

@@ -0,0 +1,39 @@
+/**
+ * `clerk doctor` MCP reachability check (folded in from the former
+ * `clerk mcp doctor` subcommand).
+ *
+ * Kept in its own file — rather than `checks.ts` — so the doctor check graph
+ * doesn't import `mcp/shared.ts` (env profiles, prompts) and the module cycle
+ * that comes with it. Imports only the light `collect`/`probe` helpers.
+ */
+
+import { collectEntries } from "../mcp/collect.ts";
+import { probeMcp } from "../mcp/probe.ts";
+import type { CheckResult } from "./types.ts";
+
+const NAME = "MCP server";
+
+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.
+  const entries = await collectEntries(process.cwd());
+  if (entries.length === 0) {
+    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})` };
+  }
+
+  const detail =
+    result.error ?? (result.status !== undefined ? `HTTP ${result.status}` : "unknown");
+  return {
+    name: NAME,
+    status: "warn",
+    message: `Configured MCP server is not reachable (${url})`,
+    detail,
+    remedy: "Verify the server is running, or re-run `clerk mcp install` if the URL changed.",
+  };
+}

packages/cli-core/src/commands/doctor/index.ts

@@ -16,6 +16,7 @@ import {
   checkShellCompletion,
   checkCliVersion,
 } from "./checks.ts";
+import { checkMcp } from "./check-mcp.ts";
 import { formatCheckResult, formatJson } from "./format.ts";
 import type { CheckFn, CheckResult, DoctorContext, DoctorOptions } from "./types.ts";
 
@@ -29,6 +30,7 @@ const BASE_CHECKS: CheckFn[] = [
   checkEnvVars,
   checkConfigFile,
   checkShellCompletion,
+  checkMcp,
 ];
 
 function getChecks(): CheckFn[] {

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

@@ -0,0 +1,77 @@
+# `clerk mcp`
+
+Manage the Clerk remote MCP server connection in supported AI clients.
+
+The Clerk MCP server is hosted at `https://mcp.clerk.com/mcp` (source:
+[clerk/cloudflare-workers/workers/remote-mcp-server](https://github.com/clerk/cloudflare-workers/tree/main/workers/remote-mcp-server)).
+These subcommands register, list, remove, and probe that URL in each client's
+own config file. The URL is resolved in order: `--url` > the `CLERK_MCP_URL`
+environment variable > the active environment profile's `mcpUrl` field
+(`switch-env` carries the profile value automatically). `CLERK_MCP_URL` is the
+convenient override when developing the worker locally (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.
+
+## Supported clients
+
+| ID            | Client                   | Scope   | Config file                           |
+| ------------- | ------------------------ | ------- | ------------------------------------- |
+| `claude-code` | Claude Code              | project | `<cwd>/.mcp.json`                     |
+| `cursor`      | Cursor                   | project | `<cwd>/.cursor/mcp.json`              |
+| `vscode`      | VS Code (Copilot)        | project | `<cwd>/.vscode/mcp.json`              |
+| `windsurf`    | Windsurf                 | user    | `~/.codeium/windsurf/mcp_config.json` |
+| `gemini`      | Gemini Code Assist / CLI | user    | `~/.gemini/settings.json`             |
+
+## Subcommands
+
+### `clerk mcp install`
+
+Register the Clerk MCP server in one or more clients.
+
+| Flag            | Description                                                                                                                                               |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--client <id>` | Target a specific client. Repeat for multiple. Default in agent mode: all detected. Default in human mode: interactive multiselect over detected clients. |
+| `--all`         | Install into every detected client without prompting.                                                                                                     |
+| `--url <url>`   | Override the MCP URL. Defaults to the active env profile's `mcpUrl`.                                                                                      |
+| `--name <name>` | Entry key in the client config. Default: `clerk`.                                                                                                         |
+| `--force`       | Overwrite an entry already pointing at a different URL. Without it, the conflict is reported and skipped.                                                 |
+| `--json`        | Emit a JSON summary on stdout instead of human-formatted output.                                                                                          |
+
+**Conflict policy:** if an entry with the same `--name` already exists and
+points at the same URL, the install is a silent no-op (`status: unchanged`).
+If it points at a different URL, the install is skipped with a `reason`
+unless `--force` is passed.
+
+**After install:** writing the config does not connect the server on its own.
+In human mode, `install` prints per-client next steps — the server only goes
+live once you **reload the editor**. If the server requires authentication, the
+editor opens a browser to **sign in** on first connect. Gemini additionally
+needs `npx` on `PATH`, since its entry launches `mcp-remote` as a stdio bridge.
+
+### `clerk mcp list`
+
+Print every Clerk-flavored MCP entry across all supported clients (entries
+named `clerk` or pointing at any `*.clerk.com` host).
+
+### `clerk mcp uninstall`
+
+Remove the named entry from each client. Throws `mcp_not_installed` (exit
+code 1) when nothing was removed. 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).
+
+## Error codes
+
+| Code                        | Meaning                                                         |
+| --------------------------- | --------------------------------------------------------------- |
+| `mcp_no_client_detected`    | No supported client found on the system.                        |
+| `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`          | No `--url` provided and the active env profile has no `mcpUrl`. |
+| `mcp_not_installed`         | `uninstall` removed nothing because no entry matched.           |

packages/cli-core/src/commands/mcp/clients/claude-code.ts

@@ -0,0 +1,22 @@
+/**
+ * Claude Code MCP client integration.
+ *
+ * Writes to `.mcp.json` in the current working directory — the project-scope
+ * config Claude Code reads automatically. Schema follows the MCP spec's HTTP
+ * transport form: `{ type: "http", url: "<endpoint>" }`.
+ */
+
+import { hasStringProp, makeJsonClient } from "./make-json-client.ts";
+import { pathExists, projectPath, userPath } from "./paths.ts";
+
+export const claudeCodeClient = makeJsonClient({
+  id: "claude-code",
+  displayName: "Claude Code",
+  scope: "project",
+  activation: "Restart Claude Code, then run `/mcp` to connect (sign in if prompted).",
+  topKey: "mcpServers",
+  encode: (url) => ({ type: "http", url }),
+  extractUrl: (d) => (hasStringProp(d, "url") ? d.url : undefined),
+  configPath: (cwd) => projectPath(cwd, ".mcp.json"),
+  detect: () => pathExists(userPath(".claude")),
+});