neon 3.4.0 → 3.5.0

package/dist/init/interactive.js

@@ -1,18 +1,17 @@
 import { FALLBACK_TEMPLATES, fetchTemplates, scaffoldTemplate } from "./bootstrap.js";
 import { detectAgent, detectIde } from "./detect_agent.js";
-import { ALL_CONFIGURABLE_AGENTS, getAddMcpAgentId } from "./agents.js";
+import { agentSupportsProjectMcp, detectInstalledAgents, getAgentDisplayName, getSkillsAgentName, mcpPickerOptions, tryResolveAddMcpAgentId } from "./agents.js";
 import { ensureNeonctlAuth, isAuthenticated } from "./auth.js";
-import { detectAvailableEditors } from "./editors.js";
-import { installExtension, isExtensionInstalled, usesExtension } from "./extension.js";
+import { installExtension, isExtensionInstalled } from "./extension.js";
 import { inspectProject } from "./inspect.js";
+import { installNeonMcpServer } from "./install_mcp.js";
 import { ensureNeonctl } from "./neonctl.js";
-import { ensureSkillsUpToDate, installAgentSkills } from "./skills.js";
+import { ensureSkillsUpToDate, installAgentSkills, skillsInstalledForAgent } from "./skills.js";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { resolve } from "node:path";
 import which from "which";
 import { SelectPrompt } from "@clack/core";
 import { confirm, isCancel, log, multiselect, outro, select, spinner } from "@clack/prompts";
-import { execa } from "execa";
 import { bold, dim, gray, italic } from "yoctocolors";
 import picocolors from "picocolors";
 //#region src/init/interactive.ts
@@ -114,8 +113,10 @@ async function interactiveInitInner(options) {
 		" ╚═╝ ╚══╝╚═════╝  ╚═════╝ ╚═╝ ╚══╝"
 	].join("\n")}\x1b[0m\n`);
 	process.stdout.write(`${dim(wordWrap("\nLet's get your project set up with Neon. We'll install the MCP server, agent skills, and IDE extension, then connect your app to a database.\n", process.stdout.columns || 80))}\n`);
-	const detectedAgentId = detectAgent();
-	const detectedEditor = detectedAgentId ? agentIdToEditor(detectedAgentId) : null;
+	const detectedAgent = (() => {
+		const raw = detectAgent();
+		return raw ? tryResolveAddMcpAgentId(raw) : void 0;
+	})();
 	const inspectSpinner = spinner();
 	inspectSpinner.start("Checking existing configuration...");
 	const inspection = await inspectProject([
@@ -216,12 +217,12 @@ async function interactiveInitInner(options) {
 		existing._init = { features: selectedFeatures };
 		writeFileSync(neonPath, `${JSON.stringify(existing, null, 2)}\n`);
 	}
-	const mcpAlready = inspection.mcpConfigured === true;
-	const skillsAlready = inspection.skillsInstalled === true || selectedTemplate !== null;
+	const mcpHits = inspection.mcpAgents ?? [];
+	const detectedHasMcp = detectedAgent ? mcpHits.some((hit) => hit.agent === detectedAgent) : false;
+	const mcpAlready = detectedAgent ? detectedHasMcp : inspection.mcpConfigured === true;
+	const skillsAlready = selectedTemplate !== null || (detectedAgent ? skillsInstalledForAgent(detectedAgent, process.cwd(), options.preview) : inspection.skillsInstalled === true);
 	const hasNeonConnection = inspection.connectionString === true;
-	let needsMcp = !mcpAlready;
-	const needsSkills = !skillsAlready;
-	const needsInstall = needsMcp || needsSkills;
+	const needsInstall = !mcpAlready || !skillsAlready;
 	const neonContextPath = resolve(process.cwd(), ".neon");
 	const hasNeonContext = existsSync(neonContextPath) && (() => {
 		try {
@@ -241,7 +242,8 @@ async function interactiveInitInner(options) {
 		return false;
 	})();
 	let extensionAlready = false;
-	if (detectedEditor && usesExtension(detectedEditor)) extensionAlready = await isExtensionInstalled(detectedEditor);
+	const detectedIdeEditor = extensionEditorForAgent(detectedAgent);
+	if (detectedIdeEditor) extensionAlready = await isExtensionInstalled(detectedIdeEditor);
 	if (mcpAlready && skillsAlready && hasNeonConnection && hasNeonContext) {
 		log.step(dim(`Neon MCP server already configured (${inspection.mcpScope || "detected"}) ✓`));
 		log.step(dim(`Neon agent skills already installed (${inspection.skillsScope || "detected"}) ✓`));
@@ -282,55 +284,39 @@ async function interactiveInitInner(options) {
 	if (mcpAlready) log.step(dim(`Neon MCP server already configured (${inspection.mcpScope || "detected"}) ✓`));
 	if (skillsAlready) log.step(dim(`Neon agent skills already installed (${inspection.skillsScope || "detected"}) ✓`));
 	if (needsInstall) {
-		const homeDir = process.env.HOME || process.env.USERPROFILE;
-		if (!homeDir) {
+		if (!(process.env.HOME || process.env.USERPROFILE)) {
 			log.error("Could not determine home directory.");
 			outro("Setup failed.");
 			return;
 		}
-		let selectedEditors;
-		if (detectedEditor) selectedEditors = [detectedEditor];
+		let selectedAgents;
+		if (detectedAgent) selectedAgents = [detectedAgent];
 		else {
-			const availableEditors = await detectAvailableEditors(homeDir);
-			const editorResponse = await multiselect({
-				message: "Which editor(s) would you like to configure?",
-				options: ALL_CONFIGURABLE_AGENTS.map((agent) => ({
-					value: agent.editor,
-					label: agent.editor,
-					hint: agent.hint
-				})),
-				initialValues: availableEditors,
-				required: true
-			});
-			if (isCancel(editorResponse)) {
-				outro("Setup cancelled.");
-				return;
-			}
-			selectedEditors = editorResponse;
-			if (selectedEditors.length === 0) {
-				log.warn("No editors selected.");
+			const picked = await pickAgents();
+			if (!picked) {
 				outro("Setup cancelled.");
 				return;
 			}
+			selectedAgents = picked;
 		}
-		const vscodeEditors = selectedEditors.filter(usesExtension);
+		let vscodeEditors = extensionEditorsFor(selectedAgents);
 		let extensionAlreadyInstalled = false;
 		if (vscodeEditors.length > 0) {
 			extensionAlreadyInstalled = (await Promise.all(vscodeEditors.map((e) => isExtensionInstalled(e)))).every(Boolean);
 			if (extensionAlreadyInstalled) log.step(dim("Neon editor extension already installed ✓"));
 		}
-		const canInstallExtension = vscodeEditors.length > 0 && !extensionAlreadyInstalled;
+		let canInstallExtension = vscodeEditors.length > 0 && !extensionAlreadyInstalled;
 		let doInstallExtension = false;
-		const hintParts = [];
-		if (needsMcp) hintParts.push("MCP server (global)");
-		if (needsSkills) hintParts.push("agent skills (project)");
 		let mcpScope = "global";
 		let skillsScope = "project";
 		let modeResult;
 		while (true) {
-			const editorName = selectedEditors.join(", ");
+			const hintParts = [];
+			if (selectedAgents.some((agent) => !mcpHits.some((hit) => hit.agent === agent))) hintParts.push("MCP server (global)");
+			if (selectedTemplate === null && selectedAgents.some((agent) => getSkillsAgentName(agent) && !skillsInstalledForAgent(agent, process.cwd(), options.preview))) hintParts.push("agent skills (project)");
+			const agentNames = selectedAgents.map((id) => getAgentDisplayName(id)).join(", ");
 			const result = await select({
-				message: `Configure ${editorName} for Neon:`,
+				message: `Configure ${agentNames} for Neon:`,
 				options: [
 					{
 						value: "defaults",
@@ -344,7 +330,7 @@ async function interactiveInitInner(options) {
 					},
 					{
 						value: "change_editor",
-						label: "Configure a different editor"
+						label: "Configure a different agent"
 					}
 				],
 				initialValue: "defaults"
@@ -354,33 +340,21 @@ async function interactiveInitInner(options) {
 				return;
 			}
 			if (result === "change_editor") {
-				const availableEditors = await detectAvailableEditors(homeDir);
-				const editorResponse = await multiselect({
-					message: "Which editor(s) would you like to configure?",
-					options: ALL_CONFIGURABLE_AGENTS.map((agent) => ({
-						value: agent.editor,
-						label: agent.editor,
-						hint: agent.hint
-					})),
-					initialValues: availableEditors,
-					required: true
-				});
-				if (isCancel(editorResponse)) {
-					outro("Setup cancelled.");
-					return;
-				}
-				selectedEditors = editorResponse;
-				if (selectedEditors.length === 0) {
+				const picked = await pickAgents();
+				if (!picked) {
 					outro("Setup cancelled.");
 					return;
 				}
+				selectedAgents = picked;
+				vscodeEditors = extensionEditorsFor(selectedAgents);
+				canInstallExtension = vscodeEditors.length > 0 && !extensionAlreadyInstalled;
 				continue;
 			}
 			modeResult = result;
 			break;
 		}
 		if (modeResult === "customize") {
-			if (needsMcp) {
+			if (selectedAgents.some((agent) => !mcpHits.some((hit) => hit.agent === agent))) {
 				const scopeResult = await select({
 					message: "Where should the Neon MCP server be configured?",
 					options: [
@@ -388,10 +362,10 @@ async function interactiveInitInner(options) {
 							value: "global",
 							label: "Global (available in all projects)"
 						},
-						{
+						...selectedAgents.every(agentSupportsProjectMcp) ? [{
 							value: "project",
 							label: "Project-level (this project only)"
-						},
+						}] : [],
 						{
 							value: "none",
 							label: "Skip — do not install the MCP server"
@@ -403,9 +377,8 @@ async function interactiveInitInner(options) {
 					return;
 				}
 				mcpScope = scopeResult;
-				if (mcpScope === "none") needsMcp = false;
 			}
-			if (needsSkills) {
+			if (selectedTemplate === null && selectedAgents.some((agent) => getSkillsAgentName(agent) && !skillsInstalledForAgent(agent, process.cwd(), options.preview))) {
 				const skillsScopeResult = await select({
 					message: "Where should Neon agent skills be installed?",
 					options: [{
@@ -444,7 +417,9 @@ async function interactiveInitInner(options) {
 		}
 		const nctlS = spinner();
 		nctlS.start("Checking Neon CLI...");
-		const nctlResult = await ensureNeonctl();
+		const nctlResult = await ensureNeonctl((phase) => {
+			nctlS.message(phase === "installing" ? "Installing Neon CLI..." : "Updating Neon CLI...");
+		});
 		switch (nctlResult.status) {
 			case "already_current":
 				nctlS.stop(dim(`Neon CLI is up to date (v${nctlResult.version}) ✓`));
@@ -456,47 +431,39 @@ async function interactiveInitInner(options) {
 				nctlS.stop(dim(`Updated Neon CLI to v${nctlResult.version} ✓`));
 				break;
 			case "failed":
-				nctlS.stop("Failed to install Neon CLI");
+				nctlS.stop(nctlResult.action === "updating" ? "Failed to update Neon CLI" : "Failed to install Neon CLI");
 				log.warn(nctlResult.error ?? "The Neon CLI could not be installed automatically.");
 				if (which.sync("npx", { nothrow: true })) log.warn("Setup will continue using npx.");
 		}
-		for (const editor of selectedEditors) {
-			if (needsMcp) {
-				const mcpArgs = [
-					"-y",
-					"add-mcp",
-					"https://mcp.neon.tech/mcp",
-					"-n",
-					"Neon",
-					"-y",
-					"-a",
-					getAddMcpAgentId(editor)
-				];
-				if (mcpScope === "global") mcpArgs.splice(5, 0, "-g");
+		for (const agent of selectedAgents) {
+			const label = getAgentDisplayName(agent);
+			if (mcpScope !== "none" && !mcpHits.some((hit) => hit.agent === agent)) {
 				const mcpS = spinner();
-				mcpS.start(`Installing Neon MCP server for ${editor}...`);
-				try {
-					await execa("npx", mcpArgs, {
-						stdio: "pipe",
-						timeout: 6e4
-					});
-					mcpS.stop(dim(`Neon MCP server configured for ${editor} (${mcpScope}) ✓`));
-				} catch (err) {
-					const msg = err instanceof Error ? err.message : "Unknown error";
-					mcpS.stop(`Failed to configure MCP server for ${editor}`);
-					log.error(msg);
+				mcpS.start(`Installing Neon MCP server for ${label}...`);
+				const installed = installNeonMcpServer({
+					agent,
+					scope: mcpScope === "project" ? "project" : "global",
+					cwd: process.cwd()
+				});
+				if (installed.ok) mcpS.stop(dim(`Neon MCP server configured for ${label} (${mcpScope}) ✓`));
+				else if (installed.unsupported) {
+					mcpS.stop(`Could not write MCP config for ${label}`);
+					log.warn(installed.error);
+				} else {
+					mcpS.stop(`Failed to configure MCP server for ${label}`);
+					log.error(installed.error);
 				}
 			}
-			if (needsSkills) await installAgentSkills([editor], {
+			if (selectedTemplate === null && getSkillsAgentName(agent) && !skillsInstalledForAgent(agent, process.cwd(), options.preview)) await installAgentSkills([agent], {
 				scope: skillsScope,
 				preview: options.preview
 			});
-			if (doInstallExtension && usesExtension(editor)) {
-				const extS = spinner();
-				extS.start(`Installing Neon extension for ${editor}...`);
-				if (await installExtension(editor)) extS.stop(dim(`Neon extension installed for ${editor} ✓`));
-				else extS.stop(`Extension install failed — install manually from the extensions panel.`);
-			}
+		}
+		if (doInstallExtension) for (const editor of vscodeEditors) {
+			const extS = spinner();
+			extS.start(`Installing Neon extension for ${editor}...`);
+			if (await installExtension(editor)) extS.stop(dim(`Neon extension installed for ${editor} ✓`));
+			else extS.stop(`Extension install failed — install manually from the extensions panel.`);
 		}
 	}
 	const ide = detectIde();
@@ -524,16 +491,37 @@ async function interactiveInitInner(options) {
 	log.message(wordWrap(promptText, cols).split("\n").map((line) => bold(neonGreenFn(line))).join("\n"));
 	outro(dim("Have feedback? Email us at feedback@neon.tech"));
 }
-function agentIdToEditor(agentId) {
-	switch (agentId) {
-		case "cursor": return "Cursor";
-		case "vscode": return "VS Code";
-		case "claude-code": return "Claude CLI";
-		case "windsurf": return null;
-		case "codex": return "Codex";
-		case "cline": return "Cline";
-		default: return null;
+function extensionEditorForAgent(agent) {
+	if (agent === "cursor") return "Cursor";
+	if (agent === "vscode") return "VS Code";
+	const ide = detectIde();
+	if (ide === "Cursor" || ide === "VS Code") return ide;
+	return null;
+}
+function extensionEditorsFor(selected) {
+	const out = [];
+	if (selected.includes("cursor")) out.push("Cursor");
+	if (selected.includes("vscode")) out.push("VS Code");
+	const ide = detectIde();
+	if ((ide === "Cursor" || ide === "VS Code") && !out.includes(ide)) out.push(ide);
+	return out;
+}
+async function pickAgents() {
+	const options = mcpPickerOptions();
+	const installed = await detectInstalledAgents();
+	const response = await multiselect({
+		message: "Which agent(s) would you like to configure?",
+		options,
+		initialValues: installed.filter((id) => options.some((option) => option.value === id)),
+		required: true
+	});
+	if (isCancel(response)) return null;
+	const selected = response;
+	if (selected.length === 0) {
+		log.warn("No agents selected.");
+		return null;
 	}
+	return selected;
 }
 //#endregion
 export { interactiveInit };

package/dist/init/neonctl.js

@@ -104,7 +104,7 @@ function isLocalDevSymlink() {
 * Ensures neonctl is globally installed and up to date.
 * Uses the same package manager that invoked the init command.
 */
-async function ensureNeonctl() {
+async function ensureNeonctl(onProgress) {
 	if (isLocalDevSymlink()) return {
 		status: "already_current",
 		version: await getNeonCliVersion() ?? "dev"
@@ -116,11 +116,14 @@ async function ensureNeonctl() {
 	};
 	const pm = resolveInvokingPackageManager();
 	const install = globalInstallCommand(pm, "neon");
+	const action = check.installed ? "updating" : "installing";
 	if (!install) return {
 		status: "failed",
-		error: "Could not install the Neon CLI: this machine has no package manager that can perform a global install. npm, pnpm and bun are not on PATH (yarn Berry has no global install). Install npm, pnpm or bun, then run this again."
+		action,
+		error: `Could not ${action === "updating" ? "update" : "install"} the Neon CLI: this machine has no package manager that can perform a global install. npm, pnpm and bun are not on PATH (yarn Berry has no global install). Install npm, pnpm or bun, then run this again.`
 	};
 	const { command, args } = install;
+	onProgress?.(action);
 	try {
 		await execa(command, args, {
 			stdio: "pipe",
@@ -134,6 +137,7 @@ async function ensureNeonctl() {
 	} catch (err) {
 		return {
 			status: "failed",
+			action,
 			error: err instanceof Error ? err.message : "Unknown error"
 		};
 	}

package/dist/init/orchestrate.js

@@ -1,5 +1,7 @@
+import { supportsSkills, tryResolveAddMcpAgentId } from "./agents.js";
 import { isAuthenticated } from "./auth.js";
 import { inspectProject } from "./inspect.js";
+import { getSkillList, missingSkillsForAgent, skillsInstalledForAgent } from "./skills.js";
 import { handleAuthPhase } from "./phases/auth.js";
 import { handleGettingStartedPhase } from "./phases/getting_started.js";
 import { handleMigrationsPhase } from "./phases/migrations.js";
@@ -62,9 +64,19 @@ async function orchestrate(options) {
 		}
 	]);
 	const hasApp = options.preview ? inspection.hasApp === true : true;
+	const requestedAgent = options.agent ? tryResolveAddMcpAgentId(options.agent) : void 0;
 	let skillsInstalled = inspection.skillsInstalled;
-	if (options.preview && skillsInstalled && inspection.skillsScope) {
-		const { getSkillList } = await import("./skills.js");
+	if (options.preview && requestedAgent && supportsSkills(requestedAgent)) {
+		const missing = missingSkillsForAgent(requestedAgent, {
+			cwd,
+			preview: true
+		});
+		const required = getSkillList(true);
+		if (missing.length > 0) {
+			skillsInstalled = false;
+			if (missing.length < required.length) inspection.skillsScope = `${inspection.skillsScope && !String(inspection.skillsScope).includes("partial") ? inspection.skillsScope : "project"}-partial`;
+		}
+	} else if (options.preview && skillsInstalled && inspection.skillsScope) {
 		const previewSkills = getSkillList(true);
 		const { existsSync: exists } = await import("node:fs");
 		const { resolve: resolvePath } = await import("node:path");
@@ -83,7 +95,9 @@ async function orchestrate(options) {
 			inspection.skillsScope = `${inspection.skillsScope}-partial`;
 		}
 	}
-	const toolingInstalled = inspection.mcpConfigured && skillsInstalled;
+	const mcpForThisAgent = requestedAgent ? (inspection.mcpAgents ?? []).some((hit) => hit.agent === requestedAgent) : inspection.mcpConfigured === true;
+	const skillsReady = requestedAgent && !supportsSkills(requestedAgent) ? true : requestedAgent ? skillsInstalledForAgent(requestedAgent, cwd, options.preview) : skillsInstalled === true;
+	const toolingInstalled = mcpForThisAgent && skillsReady;
 	const hasNeonConnection = inspection.connectionString === true;
 	if (!hasApp || !toolingInstalled) {
 		cleanupInitState(resolve(cwd, ".neon"));
@@ -91,9 +105,9 @@ async function orchestrate(options) {
 			agent: options.agent,
 			preview: options.preview,
 			hasApp,
-			mcpConfigured: inspection.mcpConfigured ?? null,
+			mcpConfigured: requestedAgent ? mcpForThisAgent : inspection.mcpConfigured ?? null,
 			mcpScope: inspection.mcpScope || void 0,
-			skillsInstalled: skillsInstalled ?? null,
+			skillsInstalled: requestedAgent ? skillsReady : skillsInstalled ?? null,
 			skillsScope: inspection.skillsScope || void 0
 		});
 	}
@@ -137,7 +151,7 @@ async function orchestrate(options) {
 		status: "complete",
 		nextAction: {
 			type: "complete",
-			message: "Neon setup is complete. Your database is configured and your agent has the Neon MCP server and skills available."
+			message: requestedAgent && !supportsSkills(requestedAgent) ? "Neon setup is complete. Your database is configured and your agent has the Neon MCP server available." : "Neon setup is complete. Your database is configured and your agent has the Neon MCP server and skills available."
 		}
 	};
 }

package/dist/init/phases/mcp.js

@@ -1,6 +1,20 @@
-import { resolveAddMcpAgentId } from "../agents.js";
+import { agentSupportsHttpMcp, agentSupportsProjectMcp, getAgentDisplayName, getSkillsAgentName, resolveAddMcpAgentId, tryResolveAddMcpAgentId } from "../agents.js";
 import { isAuthenticated } from "../auth.js";
+import { installNeonMcpServer } from "../install_mcp.js";
 //#region src/init/phases/mcp.ts
+function skillsFollowUp(agent) {
+	if (agent && !getSkillsAgentName(agent)) return agent ? [
+		"--agent",
+		agent,
+		"--json"
+	] : ["--json"];
+	return [
+		"skills",
+		"--json",
+		...agent ? ["--agent", agent] : [],
+		"--install"
+	];
+}
 async function handleMcpPhase(options) {
 	const agentArgs = options.agent ? [
 		"--agent",
@@ -40,36 +54,53 @@ async function handleMcpPhase(options) {
 		};
 		const scope = options.scope ?? "global";
 		const mcpAgentId = resolveAddMcpAgentId(options.agent ?? "claude-code");
-		const isCursor = mcpAgentId === "cursor" || options.agent?.toLowerCase() === "cursor";
-		const isClaudeCode = mcpAgentId === "claude-code" || options.agent?.toLowerCase() === "claude-code";
-		const installCmd = [
-			"npx -y add-mcp https://mcp.neon.tech/mcp",
-			scope === "global" ? "-g" : "",
-			"-n Neon",
-			"-y",
-			`-a ${mcpAgentId}`
-		].filter(Boolean).join(" ");
-		let enableNote = "";
-		if (isCursor && scope === "project") enableNote = " Note: Cursor disables project-level MCP servers by default — after installation, open Cursor Settings > MCP and toggle the \"Neon\" server on.";
-		else if (isClaudeCode) enableNote = " Note: Claude Code requires approval for newly added MCP servers. When prompted, approve the \"Neon\" server to enable it.";
-		return {
-			phase: "tooling",
-			status: "installing",
-			nextAction: {
-				type: "run_command",
-				command: installCmd,
-				description: `Installing Neon MCP server (${scope} scope) for ${mcpAgentId}.${enableNote}`,
-				timeout: 6e4,
-				onSuccess: {
-					type: "run_neon_init",
-					args: [
-						"skills",
-						"--json",
-						...options.agent ? ["--agent", options.agent] : [],
-						"--install"
-					]
-				},
-				onFailure: { other: {
+		const installed = installNeonMcpServer({
+			agent: mcpAgentId,
+			scope,
+			cwd: process.cwd()
+		});
+		if (!installed.ok) {
+			if (installed.unsupported) {
+				if (scope === "project" && !agentSupportsProjectMcp(mcpAgentId) && agentSupportsHttpMcp(mcpAgentId)) return {
+					phase: "tooling",
+					status: "unsupported",
+					error: installed.error,
+					nextAction: {
+						type: "ask_user",
+						question: `${getAgentDisplayName(mcpAgentId)} does not support project-level MCP. Install the Neon MCP server globally instead?`,
+						options: [{
+							value: "global",
+							label: "Install globally"
+						}, {
+							value: "skip",
+							label: "Skip MCP install"
+						}],
+						responseMapping: {
+							global: { args: [
+								"mcp",
+								"--json",
+								...options.agent ? ["--agent", options.agent] : [],
+								"--install"
+							] },
+							skip: { args: skillsFollowUp(options.agent) }
+						}
+					}
+				};
+				return {
+					phase: "tooling",
+					status: "unsupported",
+					error: installed.error,
+					nextAction: {
+						type: "run_neon_init",
+						args: skillsFollowUp(options.agent)
+					}
+				};
+			}
+			return {
+				phase: "tooling",
+				status: "failed",
+				error: installed.error,
+				nextAction: {
 					type: "ask_user",
 					question: "Failed to install the Neon MCP server automatically. Would you like to try again or configure it manually?",
 					options: [{
@@ -84,12 +115,28 @@ async function handleMcpPhase(options) {
 							"mcp",
 							"--json",
 							...options.agent ? ["--agent", options.agent] : [],
-							"--install"
+							"--install",
+							...scope === "project" ? ["--scope", "project"] : []
 						] },
 						manual: { args: agentArgs }
 					}
-				} }
-			}
+				}
+			};
+		}
+		const isCursor = mcpAgentId === "cursor" || options.agent?.toLowerCase() === "cursor";
+		const isClaudeCode = mcpAgentId === "claude-code" || options.agent?.toLowerCase() === "claude-code";
+		let enableNote = "";
+		if (isCursor && scope === "project") enableNote = " Cursor disables project-level MCP servers by default — open Cursor Settings > MCP and toggle the \"Neon\" server on.";
+		else if (isClaudeCode) enableNote = " Claude Code requires approval for newly added MCP servers. When prompted, approve the \"Neon\" server to enable it.";
+		return {
+			phase: "tooling",
+			status: "installed",
+			path: installed.path,
+			nextAction: {
+				type: "run_neon_init",
+				args: skillsFollowUp(options.agent)
+			},
+			message: `Installed Neon MCP server (${scope} scope) for ${mcpAgentId}.${enableNote}`
 		};
 	}
 	if (options.mcpConfigured === true) return {
@@ -97,12 +144,7 @@ async function handleMcpPhase(options) {
 		status: "mcp_configured",
 		nextAction: {
 			type: "run_neon_init",
-			args: [
-				"skills",
-				"--json",
-				...options.agent ? ["--agent", options.agent] : [],
-				"--install"
-			]
+			args: skillsFollowUp(options.agent)
 		}
 	};
 	if (options.mcpConfigured === false) return {
@@ -116,10 +158,14 @@ async function handleMcpPhase(options) {
 					value: "defaults",
 					label: "Yes, install with default settings"
 				},
-				{
-					value: "project_scope",
-					label: "Yes, install for this project only"
-				},
+				...(() => {
+					const known = options.agent ? tryResolveAddMcpAgentId(options.agent) : void 0;
+					if (known && !agentSupportsProjectMcp(known)) return [];
+					return [{
+						value: "project_scope",
+						label: "Yes, install for this project only"
+					}];
+				})(),
 				{
 					value: "skip",
 					label: "Skip for now"
@@ -141,12 +187,7 @@ async function handleMcpPhase(options) {
 					"--scope",
 					"project"
 				] },
-				skip: { args: [
-					"skills",
-					"--json",
-					...options.agent ? ["--agent", options.agent] : [],
-					"--install"
-				] }
+				skip: { args: skillsFollowUp(options.agent) }
 			}
 		}
 	};