neon 4.3.0 → 4.3.1

package/README.md

@@ -736,7 +736,7 @@ $ neon mcp -y
 # OAuth: no API key minted. The agent prompts for Neon sign-in on first use.
 $ neon mcp --oauth
 
-# Project-level config. A minted key is still account-wide.
+# Project-level config. A minted key is still account-wide unless a project is pinned.
 $ neon mcp --project
 
 $ neon mcp --agent cursor --agent claude-code
@@ -744,7 +744,7 @@ $ neon mcp --agent cursor --agent claude-code
 # Hide write tools. Does not change the minted key.
 $ neon mcp --read-only
 
-# Pin MCP tools to one project. Does not change the minted key.
+# Pin MCP tools to one project. A newly minted API key is limited to that project.
 $ neon mcp --project-id <project-id>
 
 # Limit which tool categories are visible.
@@ -753,11 +753,11 @@ $ neon mcp --category querying --category schema
 
 On a TTY the command asks for config location (global is the default), then agents, then API key vs OAuth, then a summary to confirm before it writes. Detected agents start selected: globally installed agents or project-folder markers such as `.cursor` when the install is project.
 
-`-y` skips those questions. `--project`, `--oauth` and `--agent` skip the question they answer and still apply with `-y`. `--read-only` and `--category` are flags only and are never prompted. A linked project-folder install asks whether to pin MCP tools to that `.neon` project (`?projectId=`). An unlinked project folder does not ask. Global installs never add that param unless you pass `--project-id`. Without a TTY, pass `-y` to mint into every detected agent, `--agent` to name the agents or `--oauth` to write the URL only.
+`-y` skips those questions. `--project`, `--oauth` and `--agent` skip the question they answer and still apply with `-y`. `--read-only` and `--category` are flags only and are never prompted. A linked project-folder install asks whether to pin MCP tools to that `.neon` project (`?projectId=`). If you pin and selected API-key auth, the minted key is limited to that project too. An unlinked project folder does not ask. Global installs never add that param unless you pass `--project-id`. `-y` does not infer a project from `.neon`. Without a TTY, pass `-y` to mint into every detected agent, `--agent` to name the agents or `--oauth` to write the URL only.
 
 `--agent` names: `antigravity`, `cline`, `cline-cli`, `claude-code`, `codex`, `cursor`, `gemini-cli`, `goose`, `github-copilot-cli`, `grok-build`, `mcporter`, `opencode`, `vscode`, `windsurf`, `zed`. Project installs drop `antigravity`, `cline`, `cline-cli`, `goose` and `windsurf`. `claude-desktop` is a known name that is then skipped.
 
-The default mints an account-wide API key (or reuses the Bearer already configured for Neon at `https://mcp.neon.tech/mcp`) and writes it into each selected agent's config. That key reaches everything the account can, in every organization. Revoke it with `neon api-keys revoke <id>`. `--oauth` writes the URL with no `Authorization` header; the agent signs in on first use. `--project` writes into the project config (`.cursor/mcp.json` and similar). `--read-only` adds `?readonly=true`. `--project-id` adds `?projectId=`. `--category` adds `?category=` (repeatable or comma-separated: `projects`, `branches`, `schema`, `querying`, `neon_auth`, `data_api`, `observability`, `docs`). Those query params restrict which MCP tools the server exposes; they do not change what the minted key can do.
+The default mints an account-wide API key (or reuses the Bearer already configured for Neon at `https://mcp.neon.tech/mcp`) and writes it into each selected agent's config. That key reaches everything the account can, in every organization. Revoke it with `neon api-keys revoke <id>`. `--oauth` writes the URL with no `Authorization` header; the agent signs in on first use. `--project` writes into the project config (`.cursor/mcp.json` and similar). `--read-only` adds `?readonly=true`. `--project-id` adds `?projectId=` and, when a key is minted, limits that key to the named project. Accepting the linked-project pin does the same. Revoke a project-scoped key with `neon api-keys revoke <id> --org-id <org>`. A reused Bearer keeps the scope it already has. `--category` adds `?category=` (repeatable or comma-separated: `projects`, `branches`, `schema`, `querying`, `neon_auth`, `data_api`, `observability`, `docs`). `--read-only` and `--category` restrict which MCP tools the server exposes; they do not change what the minted key can do.
 
 ## Install Neon agent skills (`skills`)
 

package/dist/commands/api_keys.js

@@ -265,16 +265,16 @@ const revoke = async (props) => {
 * scoped key — the endpoint that accepts `project_id` is org-only — so that case fails here
 * with the reason, rather than as a 404 from a URL the user never typed.
 */
-const orgIdForProject = async (client, projectId) => {
+const orgIdForProject = async (client, projectId, usage = "api-keys") => {
 	let orgId;
 	try {
 		const { data: { project } } = await client.getProject(projectId);
 		orgId = project.org_id;
 	} catch (err) {
-		if (isNeonApiError(err) && err.status === 404) throw new Error(projectId.startsWith("org-") ? `Project ${projectId} not found. That looks like an organization id. Pass it as --org-id instead.` : `Project ${projectId} not found. Check the id with \`neon projects list\`.`);
+		if (isNeonApiError(err) && err.status === 404) throw new Error(projectId.startsWith("org-") ? usage === "mcp" ? `Project ${projectId} not found. That looks like an organization id. neon mcp takes a project id on --project-id.` : `Project ${projectId} not found. That looks like an organization id. Pass it as --org-id instead.` : `Project ${projectId} not found. Check the id with \`neon projects list\`.`);
 		throw err;
 	}
-	if (!orgId) throw new Error(`Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Omit --project-id to create an account key.`);
+	if (!orgId) throw new Error(usage === "mcp" ? `Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Pass --oauth to pin tools without minting, or omit --project-id to mint an account-wide key.` : `Project ${projectId} does not belong to an organization, so it cannot have a project-scoped API key. Omit --project-id to create an account key.`);
 	return orgId;
 };
 //#endregion

package/dist/commands/mcp.js

@@ -5,7 +5,7 @@ import { getCliName } from "../utils/cli_name.js";
 import { writer } from "../writer.js";
 import { noPassthrough, single } from "../utils/flags.js";
 import { existingNeonApiKey, installNeonMcpServer, neonMcpUrl, parseMcpCategories, trackedProjectMcpConfig } from "../mcp/install.js";
-import { mintMcpApiKey, withdrawMintedKey } from "../mcp/mint.js";
+import { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey } from "../mcp/mint.js";
 import { canPickAgentsInteractively } from "../utils/agent_picker.js";
 import { resolveInstallTargets } from "../mcp/targets.js";
 import { confirmMcpInstall } from "../mcp/wizard.js";
@@ -28,7 +28,7 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 	project: {
 		type: "boolean",
 		default: false,
-		describe: "Write project-level MCP config. Skips the config-location question. Does not change the minted key"
+		describe: "Write project-level MCP config. Skips the config-location question. A linked project-folder install may still pin a project and scope a newly minted key"
 	},
 	yes: {
 		alias: "y",
@@ -59,7 +59,7 @@ const builder = (argv) => argv.usage("$0 mcp [options]").options({
 	},
 	"project-id": {
 		type: "string",
-		describe: "Pin MCP tools to one Neon project (?projectId=). Does not change the minted key. Interactive asks only for a linked project-folder install",
+		describe: "Pin MCP tools to one Neon project (?projectId=). A newly minted API key is limited to that project. A linked project-folder install asks the same when you pick API-key auth",
 		coerce: single("project-id")
 	},
 	category: {
@@ -131,7 +131,8 @@ const handler = async (props) => {
 			skipped,
 			auth: plan.auth,
 			reuse: existing !== void 0,
-			url
+			url,
+			mintProjectId: plan.urlProjectId
 		})) {
 			log.info("Aborted. Nothing was written.");
 			return;
@@ -146,13 +147,18 @@ const handler = async (props) => {
 			apiKey: existing
 		};
 		log.info("Reusing the API key already configured for the Neon MCP server.");
+		if (plan.urlProjectId) log.warning("That key keeps its existing scope. Remove the Neon MCP entry to mint a project-scoped key, or pass --oauth to pin tools without a key.");
 	} else {
-		minted = await mintMcpApiKey({ apiClient: props.apiClient });
+		minted = await mintMcpApiKey({
+			apiClient: props.apiClient,
+			projectId: plan.urlProjectId
+		});
 		auth = {
 			kind: "api-key",
 			apiKey: minted.key
 		};
-		log.warning("This key reaches everything your account can, in every organization.");
+		if (minted.projectId) log.info("Limited to %s: it cannot create projects, mint API keys, or read any other project. It can still change and delete everything inside that project.", minted.projectId);
+		else log.warning("This key reaches everything your account can, in every organization.");
 	}
 	const rows = [];
 	let successes = 0;
@@ -189,7 +195,7 @@ const handler = async (props) => {
 	if (successes === 0) {
 		if (minted && props.apiClient) {
 			const withdrawn = await withdrawMintedKey(props.apiClient, minted);
-			throw new Error(withdrawn ? "Failed to write Neon MCP config to any agent. The minted API key has been revoked." : `Failed to write Neon MCP config to any agent. The minted API key could NOT be revoked. Remove it with \`${getCliName()} api-keys revoke ${minted.id}\`.`);
+			throw new Error(withdrawn ? "Failed to write Neon MCP config to any agent. The minted API key has been revoked." : `Failed to write Neon MCP config to any agent. The minted API key could NOT be revoked. Remove it with \`${mintedKeyRevokeCommand(minted)}\`.`);
 		}
 		throw new Error("Failed to write Neon MCP config to any agent.");
 	}
@@ -204,7 +210,7 @@ const handler = async (props) => {
 		title: "MCP"
 	});
 	out.end();
-	if (minted) log.info("Minted API key %s (id %d, account). Revoke with: %s", minted.name, minted.id, `${getCliName()} api-keys revoke ${minted.id}`);
+	if (minted) log.info("Minted API key %s (id %d, %s). Revoke with: %s", minted.name, minted.id, minted.projectId ? "project" : "account", mintedKeyRevokeCommand(minted));
 	if (plan.auth === "oauth") log.info("The agent will prompt for Neon sign-in on first use.");
 	if (failedAgents.length > 0) throw new Error(`Failed to write Neon MCP config for: ${failedAgents.join(", ")}.`);
 };

package/dist/mcp/mint.js

@@ -1,24 +1,32 @@
 import { log } from "../log.js";
 import { isNeonApiError } from "../api.js";
 import { getCliName } from "../utils/cli_name.js";
+import { orgIdForProject } from "../commands/api_keys.js";
 import { mintedKeyName } from "../profile_keys.js";
 //#region src/mcp/mint.ts
 const cannotMintMessage = "This CLI credential cannot mint API keys. Organization and project-scoped keys cannot create other keys. Sign in with `neon auth` or pass a personal API key.";
-const withdraw = async (client, keyId) => {
+function mintedKeyRevokeCommand(key) {
+	return key.orgId ? `${getCliName()} api-keys revoke ${key.id} --org-id ${key.orgId}` : `${getCliName()} api-keys revoke ${key.id}`;
+}
+const withdraw = async (client, keyId, orgId) => {
 	if (!Number.isSafeInteger(keyId) || keyId === void 0 || keyId <= 0) return false;
 	try {
-		const { data } = await client.revokeApiKey(keyId);
+		const { data } = orgId ? await client.revokeOrgApiKey(orgId, keyId) : await client.revokeApiKey(keyId);
 		return data.revoked === true && data.id === keyId;
 	} catch (err) {
 		log.error("Failed to revoke API key %d: %s", keyId, err instanceof Error ? err.message : String(err));
 		return false;
 	}
 };
-const assertUsable = async (client, data, fallbackName) => {
-	const problem = typeof data.key !== "string" || data.key.trim() === "" ? "Neon returned no key." : data.project_id !== void 0 ? `Neon returned a key scoped to ${data.project_id} rather than the whole account.` : !Number.isSafeInteger(data.id) ? "Neon returned no key id." : null;
+const assertUsable = async (client, data, fallbackName, scope) => {
+	const wanted = scope.projectId;
+	const problem = typeof data.key !== "string" || data.key.trim() === "" ? "Neon returned no key." : data.project_id !== wanted ? wanted === void 0 ? `Neon returned a key scoped to ${data.project_id} rather than the whole account.` : `Neon returned a key scoped to ${data.project_id ?? "nothing"} rather than ${wanted}.` : !Number.isSafeInteger(data.id) ? "Neon returned no key id." : null;
 	if (problem) {
-		const withdrawn = await withdraw(client, data.id);
-		throw new Error(`${problem} ${withdrawn ? "The key has been revoked; nothing was issued." : `The key could NOT be revoked and may still be live${data.id === void 0 ? "" : `. Remove it with \`${getCliName()} api-keys revoke ${data.id}\``}.`}`);
+		const withdrawn = await withdraw(client, data.id, scope.orgId);
+		throw new Error(`${problem} ${withdrawn ? "The key has been revoked; nothing was issued." : `The key could NOT be revoked and may still be live${data.id === void 0 ? "" : `. Remove it with \`${mintedKeyRevokeCommand({
+			id: data.id,
+			orgId: scope.orgId
+		})}\``}.`}`);
 	}
 	const id = data.id;
 	const key = data.key;
@@ -26,21 +34,37 @@ const assertUsable = async (client, data, fallbackName) => {
 	return {
 		id,
 		name: data.name ?? fallbackName,
-		key
+		key,
+		orgId: scope.orgId,
+		projectId: scope.projectId
 	};
 };
-async function mintMcpApiKey(options) {
-	const name = mintedKeyName("mcp");
+const createAndAssert = async (client, create, name, scope) => {
 	try {
-		const { data } = await options.apiClient.createApiKey({ key_name: name });
-		return assertUsable(options.apiClient, data, name);
+		const { data } = await create();
+		return assertUsable(client, data, name, scope);
 	} catch (err) {
 		if (isNeonApiError(err) && (err.status === 403 || err.status === 404)) throw new Error(cannotMintMessage);
 		throw err;
 	}
+};
+async function mintMcpApiKey(options) {
+	const name = mintedKeyName("mcp");
+	const projectId = options.projectId;
+	if (projectId !== void 0) {
+		const orgId = await orgIdForProject(options.apiClient, projectId, "mcp");
+		return createAndAssert(options.apiClient, () => options.apiClient.createOrgApiKey(orgId, {
+			key_name: name,
+			project_id: projectId
+		}), name, {
+			orgId,
+			projectId
+		});
+	}
+	return createAndAssert(options.apiClient, () => options.apiClient.createApiKey({ key_name: name }), name, {});
 }
 async function withdrawMintedKey(apiClient, key) {
-	return withdraw(apiClient, key.id);
+	return withdraw(apiClient, key.id, key.orgId);
 }
 //#endregion
-export { mintMcpApiKey, withdrawMintedKey };
+export { mintMcpApiKey, mintedKeyRevokeCommand, withdrawMintedKey };

package/dist/mcp/plan.js

@@ -28,7 +28,7 @@ async function resolveMcpPlan(options) {
 	const auth = options.oauth ? "oauth" : prompt ? await (options.pickAuth ?? pickMcpAuth)() : "api-key";
 	let urlProjectId = options.projectId;
 	if (urlProjectId === void 0 && prompt && scope === "project" && options.linkedProjectId) {
-		if (await (options.pickProjectPin ?? pickMcpProjectPin)(options.linkedProjectId)) urlProjectId = options.linkedProjectId;
+		if (await (options.pickProjectPin ?? pickMcpProjectPin)(options.linkedProjectId, auth === "api-key")) urlProjectId = options.linkedProjectId;
 	}
 	return {
 		scope,

package/dist/mcp/wizard.js

@@ -51,20 +51,20 @@ const pickMcpAuth = async () => {
 	if (auth !== "api-key" && auth !== "oauth") throw new Error("Aborted.");
 	return auth;
 };
-const pickMcpProjectPin = async (linkedProjectId) => {
+const pickMcpProjectPin = async (linkedProjectId, willMintKey = false) => {
 	if (!canPickAgentsInteractively()) return false;
 	const { pin } = await prompts({
 		onState: restoreCursorOnAbort,
 		type: "confirm",
 		name: "pin",
-		message: `Pin MCP tools to the linked project ${linkedProjectId}?`,
+		message: willMintKey ? `Pin MCP tools to the linked project ${linkedProjectId}? A newly minted API key would be limited to that project.` : `Pin MCP tools to the linked project ${linkedProjectId}?`,
 		initial: true
 	});
 	return pin === true;
 };
 const mcpInstallSummary = (options) => {
 	const agents = options.install.map(getAgentDisplayName).join(", ");
-	const auth = options.auth === "oauth" ? "OAuth, agent signs in on first use" : options.reuse ? "reuse the API key already in agent config" : "mint an account-wide API key that reaches every organization";
+	const auth = options.auth === "oauth" ? "OAuth, agent signs in on first use" : options.reuse ? "reuse the API key already in agent config" : options.mintProjectId ? `mint an API key limited to ${options.mintProjectId}` : "mint an account-wide API key that reaches every organization";
 	const rows = [
 		["Config", options.scope === "project" ? "this directory" : "user-level"],
 		["Agents", agents],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "neon",
-  "version": "4.3.0",
+  "version": "4.3.1",
   "description": "CLI tool for Neon, the cloud backend primitives built around Lakebase Postgres",
   "keywords": [
     "neon",
@@ -64,8 +64,8 @@
     "yargs": "17.7.2",
     "yoctocolors": "^2.1.2",
     "@neon/config": "1.0.2",
-    "@neon/config-runtime": "1.0.2",
-    "@neon/sdk": "2.2.0"
+    "@neon/sdk": "2.2.0",
+    "@neon/config-runtime": "1.0.2"
   },
   "optionalDependencies": {
     "@napi-rs/keyring": "1.3.0",