feat(mcp): add clerk mcp install/list/uninstall + doctor MCP check

.changeset/mcp-install.md

@@ -0,0 +1,5 @@
+---
+"clerk": minor
+---
+
+Add `clerk mcp install`, `list`, `uninstall`, and `run` to connect the Clerk remote MCP server (`https://mcp.clerk.com/mcp`) to Claude Code, Cursor, GitHub Copilot (VS Code; `--client vscode` or `--client copilot`), Windsurf, Gemini, and Codex. Each client is configured to launch `clerk mcp run` — a built-in stdio bridge that forwards the editor's stdio JSON-RPC to the remote server over HTTP (the job `npx mcp-remote` did, now with no npx dependency), so `clerk` must be on your PATH. Entries are written to each client's user-global config (e.g. `~/.claude.json`, `~/.cursor/mcp.json`, `~/.codex/config.toml`), available across every project regardless of where you run the CLI. `clerk doctor` gains an MCP reachability check that probes each configured server via the MCP `initialize` handshake when an entry is installed. The URL resolves in order: the `CLERK_MCP_URL` override (for local worker development) > the active env profile's `mcpUrl` field > the hosted server, so `clerk mcp install` works with no flags. The bridge is transport-only for now; against an auth-required server it surfaces a clear error rather than signing in.

CONTEXT.md

@@ -0,0 +1,35 @@
+# Clerk CLI — MCP Integration
+
+The `clerk mcp` command suite connects AI tools to Clerk's remote MCP server. This context covers the domain language for registering, running, and diagnosing that connection.
+
+## Language
+
+**Client**:
+An AI tool (Claude Code, Cursor, Codex, Gemini CLI, VS Code, Windsurf) whose config file can register MCP servers.
+_Avoid_: editor, app, tool
+
+**Entry**:
+A named server record inside a Client's config file. The default entry name is `clerk`. One Client holds many Entries; `clerk mcp` only manages Clerk's.
+_Avoid_: server (that's the remote end), registration, config
+
+**Bridge**:
+The `clerk mcp run` stdio process a Client spawns. It forwards newline-delimited JSON-RPC from the Client to the remote MCP server over Streamable HTTP.
+_Avoid_: proxy, relay, server
+
+**Probe**:
+A one-shot `initialize` round-trip against an MCP URL to judge reachability. Used by `clerk doctor`; never opens a session for real work.
+_Avoid_: ping, health check
+
+**Scope**:
+Where a Client's config lives — `user` (global, e.g. `~/.claude.json`) or `project` (checked into or beside the repo). Install targets user scope.
+
+**Unreadable config**:
+A Client config file that exists but cannot be read or parsed. Distinct from "no Entry installed" — doctor must warn about the former and may skip on the latter.
+_Avoid_: missing config, empty config
+
+## Example dialogue
+
+> **Dev:** `clerk doctor` says "Skipped — no Clerk MCP entry installed", but I installed yesterday.
+> **Expert:** Then an Entry probably exists but its Client's config is an Unreadable config — doctor warns naming the Client rather than passing. Which Client? If Claude Code, check `~/.claude.json` parses.
+> **Dev:** So the Bridge is broken?
+> **Expert:** No — the Bridge only runs when a Client spawns it. This is an install-side problem: the Entry can't be read, so nothing ever spawns the Bridge. Fix the config, re-run `clerk mcp install`, and let doctor Probe the URL again.

README.md

@@ -48,6 +48,7 @@ Commands:
   disable                                         Disable Clerk features on the linked instance
   api              [options] [endpoint] [filter]  Make authenticated requests to the Clerk API
   doctor           [options]                      Check your project's Clerk integration health
+  mcp                                             Manage the Clerk remote MCP server connection for AI editors and CLIs
   completion       [shell]                        Generate shell autocompletion script
   update           [options]                      Update the Clerk CLI to the latest version
   deploy                                          Deploy a Clerk application to production

packages/cli-core/package.json

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

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

@@ -16,6 +16,7 @@ import { registerConfig } from "./commands/config/index.ts";
 import { registerToggles } from "./commands/toggles/index.ts";
 import { registerApi } from "./commands/api/index.ts";
 import { registerDoctor } from "./commands/doctor/index.ts";
+import { registerMcp } from "./commands/mcp/index.ts";
 import { registerSwitchEnv } from "./commands/switch-env/index.ts";
 import { registerCompletion } from "./commands/completion/index.ts";
 import { registerUpdate } from "./commands/update/index.ts";
@@ -68,6 +69,7 @@ const registrants: CommandRegistrant[] = [
   registerToggles,
   registerApi,
   registerDoctor,
+  registerMcp,
   registerSwitchEnv,
   registerCompletion,
   registerUpdate,

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, every distinct configured server answers the `initialize` handshake; warns on an unreadable client config (skipped when nothing is installed; warns, never fails) |
 
 ## Auto-Fix (`--fix`)
 

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

@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, mock, test } from "bun:test";
+import { useCaptureLog } from "../../test/lib/stubs.ts";
+import type { CollectResult } from "../mcp/collect.ts";
+import type { McpProbeResult } from "../mcp/probe.ts";
+import type { ListEntry } from "../mcp/clients/types.ts";
+
+let collected: CollectResult;
+let probes: Record<string, McpProbeResult>;
+let probedUrls: string[];
+
+// Registered at file top, before check-mcp.ts loads its imports (this file
+// runs in its own subprocess via scripts/run-tests.ts).
+mock.module("../mcp/collect.ts", () => ({
+  collectEntries: async () => collected,
+}));
+mock.module("../mcp/probe.ts", () => ({
+  probeMcp: async (url: string): Promise<McpProbeResult> => {
+    probedUrls.push(url);
+    return probes[url] ?? { ok: false, error: "unstubbed url" };
+  },
+}));
+
+const { checkMcp } = await import("./check-mcp.ts");
+
+const HOSTED = "https://mcp.clerk.com/mcp";
+const LOCAL = "http://localhost:9000/mcp";
+
+function entry(client: ListEntry["client"], url: string): ListEntry {
+  return { client, configPath: `/tmp/${client}.json`, name: "clerk", url };
+}
+
+describe("checkMcp", () => {
+  useCaptureLog();
+
+  beforeEach(() => {
+    collected = { entries: [], failures: [] };
+    probes = {};
+    probedUrls = [];
+  });
+
+  test("passes as skipped when nothing is installed", async () => {
+    const result = await checkMcp();
+
+    expect(result.status).toBe("pass");
+    expect(result.message).toContain("Skipped");
+  });
+
+  test("warns naming the client when a config is unreadable, instead of passing as skipped", async () => {
+    collected = {
+      entries: [],
+      failures: [{ client: "Claude Code", message: "Could not parse ~/.claude.json as JSON" }],
+    };
+
+    const result = await checkMcp();
+
+    expect(result.status).toBe("warn");
+    expect(result.message).toContain("Claude Code");
+    expect(result.detail).toContain("Could not parse");
+    expect(result.remedy).toContain("clerk mcp install");
+  });
+
+  test("still reports probe failures alongside an unreadable config", async () => {
+    collected = {
+      entries: [entry("cursor", LOCAL)],
+      failures: [{ client: "Claude Code", message: "unreadable" }],
+    };
+    probes = { [LOCAL]: { ok: false, status: 502 } };
+
+    const result = await checkMcp();
+
+    expect(result.status).toBe("warn");
+    expect(result.message).toContain("Claude Code");
+    expect(result.detail).toContain(`${LOCAL}: HTTP 502`);
+  });
+
+  test("passes with server names when every distinct URL is reachable, probing each once", async () => {
+    collected = {
+      entries: [entry("claude", HOSTED), entry("cursor", HOSTED)],
+      failures: [],
+    };
+    probes = { [HOSTED]: { ok: true, status: 200, serverName: "Clerk MCP Server" } };
+
+    const result = await checkMcp();
+
+    expect(result.status).toBe("pass");
+    expect(result.message).toBe(`Reachable — Clerk MCP Server (${HOSTED})`);
+    expect(probedUrls).toEqual([HOSTED]);
+  });
+
+  test("warns with singular wording when the only configured server is unreachable", async () => {
+    collected = { entries: [entry("claude", LOCAL)], failures: [] };
+    probes = { [LOCAL]: { ok: false, error: "fetch failed" } };
+
+    const result = await checkMcp();
+
+    expect(result.status).toBe("warn");
+    expect(result.message).toContain("Configured MCP server is not reachable");
+    expect(result.detail).toBe(`${LOCAL}: fetch failed`);
+  });
+
+  test("a healthy first URL does not mask a broken second", async () => {
+    collected = {
+      entries: [entry("claude", HOSTED), entry("cursor", LOCAL)],
+      failures: [],
+    };
+    probes = {
+      [HOSTED]: { ok: true, status: 200, serverName: "Clerk MCP Server" },
+      [LOCAL]: { ok: false, error: "fetch failed" },
+    };
+
+    const result = await checkMcp();
+
+    expect(result.status).toBe("warn");
+    expect(result.message).toContain("One or more configured MCP servers are not reachable");
+    expect(result.message).toContain(LOCAL);
+    expect(result.message).not.toContain(HOSTED);
+  });
+});

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

@@ -0,0 +1,84 @@
+/**
+ * `clerk doctor` MCP reachability check.
+ *
+ * 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, type McpProbeResult } from "../mcp/probe.ts";
+import type { ListEntry } from "../mcp/clients/types.ts";
+import type { CheckResult } from "./types.ts";
+
+const NAME = "MCP server";
+
+type UrlProbe = { url: string; result: McpProbeResult };
+type ReachableProbe = { url: string; result: Extract<McpProbeResult, { ok: true }> };
+
+// Narrowed to the reachable variant: only called once every probe succeeded.
+function describeReachable(probes: ReachableProbe[]): string {
+  return probes.map(({ url, result }) => `${result.serverName} (${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";
+}
+
+function describeUnreachable(unreachable: UrlProbe[], total: number): string {
+  const subject =
+    total === 1 ? "Configured MCP server is" : "One or more configured MCP servers are";
+  return `${subject} not reachable (${unreachable.map((p) => p.url).join(", ")})`;
+}
+
+// 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.
+async function probeEntries(entries: ListEntry[]): Promise<UrlProbe[]> {
+  const urls = [...new Set(entries.map((e) => e.url))];
+  return Promise.all(urls.map(async (url) => ({ url, result: await probeMcp(url) })));
+}
+
+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, failures } = await collectEntries(process.cwd());
+  const probes = await probeEntries(entries);
+  const unreachable = probes.filter((p): p is UrlProbe => !p.result.ok);
+
+  // An unreadable client config is not "nothing installed" — a previously
+  // registered entry may be hiding inside it. The stderr warning alone gets
+  // clobbered by the doctor spinner, so it must surface in the check result.
+  if (failures.length > 0) {
+    const clients = failures.map((f) => f.client).join(", ");
+    return {
+      name: NAME,
+      status: "warn",
+      message: `Could not read the MCP config for ${clients}`,
+      detail: [
+        ...failures.map((f) => `${f.client}: ${f.message}`),
+        ...unreachable.map((p) => `${p.url}: ${describeFailure(p.result)}`),
+      ].join("; "),
+      remedy: "Fix or remove the unreadable config file, then re-run `clerk mcp install`.",
+    };
+  }
+
+  if (entries.length === 0) {
+    return { name: NAME, status: "pass", message: "Skipped (no Clerk MCP entry installed)" };
+  }
+
+  if (unreachable.length === 0) {
+    const reachable = probes.filter((p): p is ReachableProbe => p.result.ok);
+    return { name: NAME, status: "pass", message: `Reachable — ${describeReachable(reachable)}` };
+  }
+
+  return {
+    name: NAME,
+    status: "warn",
+    message: describeUnreachable(unreachable, probes.length),
+    detail: unreachable.map((p) => `${p.url}: ${describeFailure(p.result)}`).join("; "),
+    remedy: "Verify the server is running, or re-run `clerk mcp install` if the URL changed.",
+  };
+}

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

@@ -1,11 +1,6 @@
-import { test, expect, describe, mock, beforeEach, afterEach } from "bun:test";
-import {
-  useCaptureLog,
-  credentialStoreStubs,
-  configStubs,
-  gitStubs,
-  stubFetch,
-} from "../../test/lib/stubs.ts";
+import { test, expect, describe, mock, spyOn, beforeEach, afterEach, afterAll } from "bun:test";
+import { useCaptureLog, credentialStoreStubs, gitStubs, stubFetch } from "../../test/lib/stubs.ts";
+import * as config from "../../lib/config.ts";
 import type { Application } from "../../lib/plapi.ts";
 
 const mockGetToken = mock();
@@ -15,12 +10,13 @@ mock.module("../../lib/credential-store.ts", () => ({
   getToken: (...args: unknown[]) => mockGetToken(...args),
 }));
 
+// spyOn (not mock.module) for config: a spy is restorable, so afterAll hands the
+// real module back to doctor.test.ts when both run in one `bun test` process.
 const mockResolveProfile = mock();
-
-mock.module("../../lib/config.ts", () => ({
-  ...configStubs,
-  resolveProfile: (...args: unknown[]) => mockResolveProfile(...args),
-}));
+const resolveProfileSpy = spyOn(config, "resolveProfile").mockImplementation((...args: unknown[]) =>
+  mockResolveProfile(...(args as [string])),
+);
+afterAll(() => resolveProfileSpy.mockRestore());
 
 mock.module("../../lib/git.ts", () => gitStubs);
 
@@ -70,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/index.ts

@@ -17,6 +17,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";
 
@@ -30,6 +31,7 @@ const BASE_CHECKS: CheckFn[] = [
   checkEnvVars,
   checkConfigFile,
   checkShellCompletion,
+  checkMcp,
 ];
 
 function getChecks(): CheckFn[] {