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

[rafa-thayto]

Summary

Adds a clerk mcp command group to register the Clerk remote MCP server (https://mcp.clerk.com/mcp) into supported AI editors, plus an MCP health check in clerk doctor.

• clerk mcp install — register the server in one or more clients. Interactive multiselect in human mode; all detected clients in agent mode. Flags: --client (repeatable), --all, --url, --name, --force, --json. Conflict policy: same URL → unchanged (no-op); different URL → skipped with a reason unless --force.
• clerk mcp list — show every Clerk-flavored entry (named clerk or pointing at any *.clerk.com host) across all clients.
• clerk mcp uninstall — remove the entry. In human mode it prompts with a multiselect of the clients that actually have it, so you pick exactly which to remove from; --all removes from every client without prompting (agent mode targets all); --client targets specific clients. Throws mcp_not_installed (exit 1) when nothing matched.
• clerk doctor — gains an MCP server check that probes the configured server via the MCP initialize handshake only when an entry is installed (skips otherwise; warns, never fails — a server outage shouldn't fail the whole doctor run). There is intentionally no separate clerk mcp doctor — one doctor.

Supported clients — all user-global scope

Entries are written to each client's user-global config, so the server is available in every project, with no per-project approval and no dependence on the directory the CLI is run from.

Client	--client id	Config file
Claude Code	claude	~/.claude.json (mcpServers)
Cursor	cursor	~/.cursor/mcp.json
VS Code	vscode	~/Library/Application Support/Code/User/mcp.json (per-OS)
Windsurf	windsurf	~/.codeium/windsurf/mcp_config.json
Gemini	gemini	~/.gemini/settings.json (npx mcp-remote stdio bridge)

Each editor gets its own descriptor schema ({type:http,url} / {url} / {serverUrl} / npx mcp-remote args).

Design notes

• Works out of the box: URL resolution is --url > CLERK_MCP_URL env > active env profile mcpUrl (new field) > Clerk's hosted server (default), so clerk mcp install needs no flags or profile setup.
• Next steps matter: writing a config doesn't connect the editor (reload + sign in if prompted; Gemini needs npx on PATH), and removing it doesn't drop a live session (reload). Human-mode output uses the prompt rail — intro/outro gutter, a "Next steps" block, and interactive multiselect pickers for install/uninstall.
• No Clerk API is called — the only network call is the doctor probe to the MCP URL itself.
• Resilient & safe: one client's malformed config warns and is skipped rather than aborting the command (Promise.allSettled); own-property guards avoid prototype pollution; --url scheme is validated (http/https only).

Test plan

• bun run format:check, bun run lint, bun run typecheck — green
• bun test for the feature — 132 mcp + doctor tests passing (per-client encode/extract round-trips, conflict policy incl. --force, prototype-key names, malformed-config handling, the doctor initialize handshake across application/json + SSE transports, hosted-URL fallback when a profile omits mcpUrl, the uninstall picker selecting a subset, --all, unknown --client, multi-client partial failure, gutter/next-steps output). Tests redirect homedir() to a tmpdir so user-scoped writes stay isolated.
• Integration suite green
• Manual: install → list → doctor → uninstall end-to-end against the live server (handshake returns Clerk MCP Server); verified configs land in the user-global paths regardless of cwd; partial-failure path verified with a corrupted client config

[changeset-bot]

🦋 Changeset detected

Latest commit: 8a62c01

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
clerk	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This PR adds MCP server support to the Clerk CLI: new subcommands (clerk mcp install/list/uninstall), a JSON-backed client factory and five client integrations (Claude Code, Cursor, VS Code, Windsurf, Gemini), per-client config read/write helpers, collection of installed entries, an initialize-handshake probe supporting JSON and SSE with a 10s timeout, a doctor check (checkMcp), environment/profile mcpUrl wiring, CLI wiring, comprehensive tests, and documentation including a changeset and README updates.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 24.44% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The PR title clearly and concisely summarizes the main feature: adding clerk mcp install/list/uninstall commands plus an MCP doctor check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description clearly relates to and describes the changeset: it documents the new clerk mcp commands (install, list, uninstall), their flags, client support, and the doctor MCP check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[rafa-thayto]

!snapshot

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/cli-core/src/commands/mcp/clients/user-scope.test.ts (1)

2-2: ⚡ Quick win

Use Bun file APIs here instead of node:fs read/write helpers.

These tests currently use readFile/writeFile from node:fs/promises, which goes against the repo’s Bun-specific file I/O guideline. Bun.file(...).json()/text() and Bun.write(...) would keep this aligned with the rest of the codebase. As per coding guidelines, **/*.{ts,tsx,js,jsx}: Prefer Bun.file over node:fs's readFile/writeFile for file operations.

Also applies to: 45-46, 64-66

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@packages/cli-core/src/commands/mcp/clients/user-scope.test.ts` at line 2,
Replace node:fs/promises read/write helpers imported as mkdir, mkdtemp,
readFile, rm, writeFile in user-scope.test.ts with Bun file APIs: use
Bun.file(path).text()/json() for reads and Bun.write/Bun.writeSync (or
Bun.file(path).write(...)) for writes, and keep using mkdtemp/mkdir/rm
equivalents via Bun or the existing helpers if available; update all call sites
that use readFile/writeFile (and any promise-based usages) to the corresponding
Bun.file(...).text()/json() and Bun.write(...) patterns so the tests follow the
repo’s Bun-specific I/O guideline.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cli-core/src/commands/mcp/clients/user-scope.test.ts`:
- Around line 7-12: The top-level module mock of node:os (mock.module("node:os",
...)) is never torn down causing cross-test leakage; add a cleanup via
afterAll(() => mock.restoreModule("node:os")) (or equivalent) to restore the
original module and avoid order-dependent failures, and update file I/O in this
test to use Bun APIs instead of node:fs/promises—replace readFile/writeFile
calls with Bun.file(path).json()/text() for reads and Bun.file(path).write(...)
or Bun.write(...) for writes so the test uses Bun's file operations correctly;
reference mock.module, mock.restoreModule, mockHome and the test file's existing
fs read/write usages when making the changes.

---

Nitpick comments:
In `@packages/cli-core/src/commands/mcp/clients/user-scope.test.ts`:
- Line 2: Replace node:fs/promises read/write helpers imported as mkdir,
mkdtemp, readFile, rm, writeFile in user-scope.test.ts with Bun file APIs: use
Bun.file(path).text()/json() for reads and Bun.write/Bun.writeSync (or
Bun.file(path).write(...)) for writes, and keep using mkdtemp/mkdir/rm
equivalents via Bun or the existing helpers if available; update all call sites
that use readFile/writeFile (and any promise-based usages) to the corresponding
Bun.file(...).text()/json() and Bun.write(...) patterns so the tests follow the
repo’s Bun-specific I/O guideline.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 33d9756c-11d6-436b-8465-7e750f438029

📥 Commits

Reviewing files that changed from the base of the PR and between 292e92f and 4f53e9f.

📒 Files selected for processing (34)

• .changeset/mcp-install.md
• README.md
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/doctor/README.md
• packages/cli-core/src/commands/doctor/check-mcp.ts
• packages/cli-core/src/commands/doctor/context.test.ts
• packages/cli-core/src/commands/doctor/index.ts
• packages/cli-core/src/commands/mcp/README.md
• packages/cli-core/src/commands/mcp/clients/claude-code.ts
• packages/cli-core/src/commands/mcp/clients/clients.test.ts
• packages/cli-core/src/commands/mcp/clients/cursor.ts
• packages/cli-core/src/commands/mcp/clients/gemini.ts
• packages/cli-core/src/commands/mcp/clients/json-config.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.test.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.ts
• packages/cli-core/src/commands/mcp/clients/paths.ts
• packages/cli-core/src/commands/mcp/clients/registry.ts
• packages/cli-core/src/commands/mcp/clients/types.ts
• packages/cli-core/src/commands/mcp/clients/user-scope.test.ts
• packages/cli-core/src/commands/mcp/clients/vscode.ts
• packages/cli-core/src/commands/mcp/clients/windsurf.ts
• packages/cli-core/src/commands/mcp/collect.ts
• packages/cli-core/src/commands/mcp/index.ts
• packages/cli-core/src/commands/mcp/install.test.ts
• packages/cli-core/src/commands/mcp/install.ts
• packages/cli-core/src/commands/mcp/list.test.ts
• packages/cli-core/src/commands/mcp/list.ts
• packages/cli-core/src/commands/mcp/probe.test.ts
• packages/cli-core/src/commands/mcp/probe.ts
• packages/cli-core/src/commands/mcp/shared.ts
• packages/cli-core/src/commands/mcp/uninstall.test.ts
• packages/cli-core/src/commands/mcp/uninstall.ts
• packages/cli-core/src/lib/environment.ts
• packages/cli-core/src/lib/errors.ts

✅ Files skipped from review due to trivial changes (4)

• .changeset/mcp-install.md
• packages/cli-core/src/commands/doctor/README.md
• README.md
• packages/cli-core/src/commands/mcp/README.md

🚧 Files skipped from review as they are similar to previous changes (26)

• packages/cli-core/src/commands/mcp/list.test.ts
• packages/cli-core/src/commands/mcp/clients/registry.ts
• packages/cli-core/src/commands/mcp/index.ts
• packages/cli-core/src/commands/mcp/clients/claude-code.ts
• packages/cli-core/src/commands/mcp/clients/cursor.ts
• packages/cli-core/src/commands/mcp/list.ts
• packages/cli-core/src/commands/mcp/clients/vscode.ts
• packages/cli-core/src/commands/doctor/check-mcp.ts
• packages/cli-core/src/commands/mcp/clients/gemini.ts
• packages/cli-core/src/commands/mcp/clients/windsurf.ts
• packages/cli-core/src/commands/mcp/clients/types.ts
• packages/cli-core/src/commands/mcp/probe.test.ts
• packages/cli-core/src/lib/errors.ts
• packages/cli-core/src/commands/doctor/index.ts
• packages/cli-core/src/commands/mcp/clients/paths.ts
• packages/cli-core/src/commands/mcp/install.ts
• packages/cli-core/src/lib/environment.ts
• packages/cli-core/src/commands/mcp/collect.ts
• packages/cli-core/src/commands/mcp/uninstall.ts
• packages/cli-core/src/commands/mcp/clients/clients.test.ts
• packages/cli-core/src/commands/mcp/probe.ts
• packages/cli-core/src/commands/mcp/install.test.ts
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/mcp/clients/json-config.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.test.ts
• packages/cli-core/src/commands/mcp/uninstall.test.ts

[rafa-thayto]

!snapshot

[github-actions]

Snapshot published

npm install -g clerk@2.0.1-snapshot.bdf8faf

Package	Version
clerk	2.0.1-snapshot.bdf8faf

Published from bdf8faf

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/cli-core/src/commands/mcp/clients/clients.test.ts`:
- Around line 65-96: The VS Code test is leaking to the real config because
vscodeUserDir() respects XDG_CONFIG_HOME/APPDATA; update the tests to isolate
that by setting XDG_CONFIG_HOME and APPDATA to a directory under mockHome (or
delete them) before running the VS Code-specific assertions and restore them
after; ensure the expectation for the VS Code path does not call vscodeUserDir()
(i.e. compute the expected path explicitly inside the test instead of reusing
expectedPath()/vscodeUserDir()) so the test verifies the function under test
rather than mirroring the same helper.

In `@packages/cli-core/src/commands/mcp/clients/paths.ts`:
- Around line 26-35: vscodeUserDir currently uses the nullish coalescing
operator (??) with process.env.APPDATA and process.env.XDG_CONFIG_HOME which
treats empty strings as set; update vscodeUserDir to treat empty or
whitespace-only env vars as unset by checking truthiness/trim (e.g. derive local
vars like appData = process.env.APPDATA?.trim() ? process.env.APPDATA :
undefined and xdg = process.env.XDG_CONFIG_HOME?.trim() ?
process.env.XDG_CONFIG_HOME : undefined) and then fall back to join(homedir(),
...) in the switch cases; reference the vscodeUserDir function and its uses of
process.env.APPDATA and process.env.XDG_CONFIG_HOME, and ensure platform(),
homedir(), and join() behavior is preserved.

In `@packages/cli-core/src/lib/environment.ts`:
- Around line 154-165: getMcpUrl currently lets an empty CLERK_MCP_URL ("") win
due to the nullish coalescing operator; treat empty/whitespace-only env values
as unset by trimming and checking truthiness before falling back. Update
getMcpUrl (function name: getMcpUrl) to compute const env =
process.env.CLERK_MCP_URL?.trim(); then return env && env.length ? env :
getCurrentEnv().mcpUrl ?? DEFAULT_MCP_URL so blank overrides no longer produce
an unusable empty string.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 2826916f-5886-46c5-96c7-da4b8e7b1a92

📥 Commits

Reviewing files that changed from the base of the PR and between bdf8faf and d80abcd.

📒 Files selected for processing (23)

• .changeset/mcp-install.md
• packages/cli-core/src/cli-program.ts
• packages/cli-core/src/commands/doctor/check-mcp.ts
• packages/cli-core/src/commands/mcp/README.md
• packages/cli-core/src/commands/mcp/clients/claude-code.ts
• packages/cli-core/src/commands/mcp/clients/clients.test.ts
• packages/cli-core/src/commands/mcp/clients/cursor.ts
• packages/cli-core/src/commands/mcp/clients/gemini.ts
• packages/cli-core/src/commands/mcp/clients/json-config.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.test.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.ts
• packages/cli-core/src/commands/mcp/clients/paths.ts
• packages/cli-core/src/commands/mcp/clients/user-scope.test.ts
• packages/cli-core/src/commands/mcp/clients/vscode.ts
• packages/cli-core/src/commands/mcp/clients/windsurf.ts
• packages/cli-core/src/commands/mcp/install.test.ts
• packages/cli-core/src/commands/mcp/install.ts
• packages/cli-core/src/commands/mcp/list.test.ts
• packages/cli-core/src/commands/mcp/list.ts
• packages/cli-core/src/commands/mcp/shared.ts
• packages/cli-core/src/commands/mcp/uninstall.test.ts
• packages/cli-core/src/lib/environment.ts
• packages/cli-core/src/lib/errors.ts

💤 Files with no reviewable changes (3)

• packages/cli-core/src/commands/mcp/clients/gemini.ts
• packages/cli-core/src/commands/mcp/clients/windsurf.ts
• packages/cli-core/src/cli-program.ts

✅ Files skipped from review due to trivial changes (2)

• .changeset/mcp-install.md
• packages/cli-core/src/commands/mcp/README.md

🚧 Files skipped from review as they are similar to previous changes (12)

• packages/cli-core/src/commands/mcp/clients/cursor.ts
• packages/cli-core/src/lib/errors.ts
• packages/cli-core/src/commands/mcp/clients/vscode.ts
• packages/cli-core/src/commands/mcp/list.ts
• packages/cli-core/src/commands/doctor/check-mcp.ts
• packages/cli-core/src/commands/mcp/uninstall.test.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.test.ts
• packages/cli-core/src/commands/mcp/clients/user-scope.test.ts
• packages/cli-core/src/commands/mcp/shared.ts
• packages/cli-core/src/commands/mcp/clients/json-config.ts
• packages/cli-core/src/commands/mcp/clients/make-json-client.ts
• packages/cli-core/src/commands/mcp/install.test.ts

[rafa-thayto]

!snapshot

[github-actions]

Snapshot published

npm install -g clerk@2.0.1-snapshot.d637eb0

Package	Version
clerk	2.0.1-snapshot.d637eb0

Published from d637eb0