envpkt 0.14.1 → 0.15.0

package/README.md

@@ -584,6 +584,21 @@ Inject resolved secrets into a GitHub Actions job. Emits `::add-mask::` for each
 npx envpkt env github --strict
 ```
 
+### `envpkt headers`
+
+Print the HTTP headers for one MCP server as JSON, for Claude Code's `headersHelper`. Bind a secret to a server with `mcp = [{ server = "civala-github" }]` (optional `header`, default `"Authorization"`; `scheme`, default `"Bearer"`, `""` for the raw value).
+
+```bash
+envpkt headers civala-github   # {"Authorization":"Bearer ..."}
+envpkt headers                 # server from $CLAUDE_CODE_MCP_SERVER_NAME
+```
+
+```json
+{ "type": "http", "url": "https://github.civala.ai/mcp", "headersHelper": "envpkt headers" }
+```
+
+stdout holds only the JSON; warnings and errors go to stderr. It decrypts sealed values through `identity.key_file`, so it works when Claude was launched with a stripped environment and `${VAR}` refs in `.mcp.json` would expand empty. Exits non-zero, naming the server, when nothing matches or a value does not resolve. Without `-c`, it finds `envpkt.toml` like every other command, falling back to the global package when the project has none.
+
 ### `envpkt mcp`
 
 Start the envpkt MCP server (stdio transport) for AI agent integration.

package/dist/cli.js

@@ -123,14 +123,15 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 	const staleWarningDays = lifecycle.stale_warning_days ?? 90;
 	const requireExpiration = lifecycle.require_expiration ?? false;
 	const requireService = lifecycle.require_service ?? false;
-	const keys = fnoxKeys ?? /* @__PURE__ */ new Set();
+	const keys = fnoxKeys ?? Set$1.empty();
 	const secretEntries = config.secret ?? {};
 	const nonAliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0);
 	const aliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0);
 	const nonAliasHealth = nonAliasEntries.map(([key, meta]) => classifySecret(key, meta, keys, staleWarningDays, requireExpiration, requireService, now));
 	const healthByKey = Map$1(nonAliasHealth.map((h) => [h.key, h]));
 	const parseTargetKey = (from_key) => {
-		return Option(from_key.match(/^secret\.(.+)$/)?.[1]);
+		const match = from_key.match(/^secret\.(.+)$/);
+		return Option(match?.[1]);
 	};
 	const aliasHealth = aliasEntries.map(([key, meta]) => {
 		const tableEntry = aliasTable?.entries.get(`secret.${key}`);
@@ -184,8 +185,10 @@ const computeEnvAudit = (config, env = process.env) => {
 	const envWire = (key) => namer(key, envEntries[key]?.namespace);
 	const resolveEffectiveDefault = (entry) => {
 		return Do(function* () {
-			const targetKey = yield* $(Option((yield* $(Option(entry.from_key))).match(/^env\.(.+)$/)?.[1]));
-			return yield* $(Option((yield* $(Option(envEntries[targetKey]))).value));
+			const fk = yield* $(Option(entry.from_key));
+			const targetKey = yield* $(Option(fk.match(/^env\.(.+)$/)?.[1]));
+			const targetEntry = yield* $(Option(envEntries[targetKey]));
+			return yield* $(Option(targetEntry.value));
 		}).orElse(entry.value ?? "");
 	};
 	const entries = Object.entries(envEntries).map(([key, entry]) => {
@@ -241,6 +244,21 @@ const NamespaceSchema = Type.Object({
 		description: "Separator between prefix and key. Default '__' (shell-safe). Note: '.' and ':' are not valid in shell identifiers."
 	}))
 }, { description: "Optional namespace/package prefix for injected environment variable names" });
+const McpHeaderSchema = Type.Object({
+	server: Type.String({
+		minLength: 1,
+		description: "MCP server name, as keyed in .mcp.json"
+	}),
+	header: Type.Optional(Type.String({
+		default: "Authorization",
+		minLength: 1,
+		description: "HTTP header name to send the secret in"
+	})),
+	scheme: Type.Optional(Type.String({
+		default: "Bearer",
+		description: "Prefix placed before the value (e.g. 'Bearer'). Empty string sends the raw value."
+	}))
+}, { description: "Send this secret as an HTTP header to an MCP server" });
 const SecretMetaSchema = Type.Object({
 	service: Type.Optional(Type.String({ description: "Service or system this secret authenticates to" })),
 	expires: Type.Optional(Type.String({
@@ -271,7 +289,8 @@ const SecretMetaSchema = Type.Object({
 	required: Type.Optional(Type.Boolean({ description: "Whether this secret is required for operation" })),
 	external: Type.Optional(Type.Boolean({ description: "Value is managed outside envpkt (e.g. a Cloudflare/Vault secret). The entry registers the name for inventory and dev/prod parity only: seal never touches it, and audit reports it as 'external' rather than 'missing'." })),
 	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" })),
-	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." }))
+	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." })),
+	mcp: Type.Optional(Type.Array(McpHeaderSchema, { description: "MCP servers this secret authenticates to. Read by `envpkt headers` (Claude Code headersHelper)." }))
 }, { description: "Metadata about a single secret" });
 const LifecycleConfigSchema = Type.Object({
 	stale_warning_days: Type.Optional(Type.Number({
@@ -399,10 +418,13 @@ const discoverConfig = (cwd) => {
 		template,
 		expanded: expandPath(template)
 	})).filter(({ expanded }) => expanded !== "" && !expanded.startsWith("/.envpkt")).map(({ expanded }) => expandGlobPath(expanded)).find((matches) => matches.length > 0);
-	if (customMatch) return Option({
-		path: customMatch[0],
-		source: "search"
-	});
+	if (customMatch) {
+		const found = {
+			path: customMatch[0],
+			source: "search"
+		};
+		return Option(found);
+	}
 	const platformMatch = buildSearchPaths().find((p) => Fs.existsSync(p));
 	if (platformMatch) return Option({
 		path: platformMatch,
@@ -444,9 +466,10 @@ const parseToml = (raw) => Try(() => parse(raw)).fold((err) => Left({
 /** Validate parsed data against the TypeBox schema */
 const validateConfig = (data) => {
 	if (compiledSchema.Check(data)) return Right(data);
+	const errors = List([...compiledSchema.Errors(data)].map((e) => `${e.path}: ${e.message}`));
 	return Left({
 		_tag: "ValidationError",
-		errors: List([...compiledSchema.Errors(data)].map((e) => `${e.path}: ${e.message}`))
+		errors
 	});
 };
 /** Load and validate an envpkt.toml from a file path */
@@ -856,7 +879,8 @@ const runAudit = (options) => {
 			console.error(formatError(err));
 			process.exit(2);
 		}, (rawConfig) => {
-			resolveConfig(rawConfig, dirname(path)).fold((err) => {
+			const configDir = dirname(path);
+			resolveConfig(rawConfig, configDir).fold((err) => {
 				console.error(formatError(err));
 				process.exit(2);
 			}, (resolveResult) => {
@@ -920,8 +944,10 @@ const runAuditOnConfig = (config, options) => {
 	if (options.format === "json") console.log(formatAuditJson(sorted));
 	else if (options.format === "minimal") console.log(formatAuditMinimal(sorted));
 	else console.log(formatAudit(sorted));
-	if (options.all) if (options.format === "json") console.log(formatEnvAuditJson(config));
-	else formatEnvAuditTable(config);
+	if (options.all) {
+		if (options.format === "json") console.log(formatEnvAuditJson(config));
+		else formatEnvAuditTable(config);
+	}
 	const code = options.strict ? exitCodeForAudit(audit) : audit.status === "critical" ? 2 : 0;
 	process.exit(code);
 };
@@ -1497,7 +1523,8 @@ const bootSafe = (options) => {
 			_tag: "ReadError",
 			message: "unexpected"
 		}));
-		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
+		const fnoxKeys = detectFnoxKeys(configDir);
+		const audit = computeAudit(config, fnoxKeys, void 0, aliasTable);
 		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
 		if (hasSealedValues && sealIdentity.isEmpty) return Left({
 			_tag: "SealKeyUnavailable",
@@ -1539,37 +1566,39 @@ const bootSafe = (options) => {
 				}
 			});
 			const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
-			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
-				log.warn("phase.fnox.export_failed", {
-					message: err.message,
-					skipped: remainingKeys.length
-				});
-				warnings.push(`fnox export failed: ${err.message}`);
-				skipped.push(...remainingKeys);
-			}, (exported) => {
-				const found = remainingKeys.filter((key) => key in exported);
-				const notFound = remainingKeys.filter((key) => !(key in exported));
-				found.forEach((key) => {
-					secrets[key] = exported[key];
-					log.debug("phase.fnox.resolved", {
-						key,
-						profile: opts.profile
+			if (remainingKeys.length > 0) {
+				if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
+					log.warn("phase.fnox.export_failed", {
+						message: err.message,
+						skipped: remainingKeys.length
 					});
-				});
-				notFound.forEach((key) => {
-					log.debug("phase.fnox.not_in_export", {
-						key,
-						profile: opts.profile
+					warnings.push(`fnox export failed: ${err.message}`);
+					skipped.push(...remainingKeys);
+				}, (exported) => {
+					const found = remainingKeys.filter((key) => key in exported);
+					const notFound = remainingKeys.filter((key) => !(key in exported));
+					found.forEach((key) => {
+						secrets[key] = exported[key];
+						log.debug("phase.fnox.resolved", {
+							key,
+							profile: opts.profile
+						});
+					});
+					notFound.forEach((key) => {
+						log.debug("phase.fnox.not_in_export", {
+							key,
+							profile: opts.profile
+						});
 					});
+					injected.push(...found);
+					skipped.push(...notFound);
 				});
-				injected.push(...found);
-				skipped.push(...notFound);
-			});
-			else {
-				log.debug("phase.fnox.unavailable", { skipped: remainingKeys.length });
-				if (!hasSealedValues) warnings.push("fnox not available — no secrets injected");
-				else warnings.push("fnox not available — unsealed secrets could not be resolved");
-				skipped.push(...remainingKeys);
+				else {
+					log.debug("phase.fnox.unavailable", { skipped: remainingKeys.length });
+					if (!hasSealedValues) warnings.push("fnox not available — no secrets injected");
+					else warnings.push("fnox not available — unsealed secrets could not be resolved");
+					skipped.push(...remainingKeys);
+				}
 			}
 			aliasSecretKeys.forEach((aliasKey) => {
 				const entry = aliasTable.entries.get(`secret.${aliasKey}`);
@@ -1964,16 +1993,114 @@ const sortConfigToml = (raw) => {
 	return `${parts.join("\n\n")}\n`;
 };
 //#endregion
+//#region src/core/mcp-headers.ts
+const DEFAULT_HEADER = "Authorization";
+const DEFAULT_SCHEME = "Bearer";
+/** RFC 9110 `token`: the legal characters of a header name (and of an auth scheme). */
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Characters that would split or corrupt an HTTP header value. */
+const UNSAFE_VALUE_RE = /[\r\n\0]/;
+/** Flatten every `[secret.*].mcp` entry into one binding per (secret, server), with defaults applied. */
+const collectBindings = (config) => Object.entries(config.secret ?? {}).flatMap(([key, meta]) => (meta.mcp ?? []).map((m) => ({
+	key,
+	server: m.server,
+	header: m.header ?? DEFAULT_HEADER,
+	scheme: m.scheme ?? DEFAULT_SCHEME
+})));
+/**
+* Check bindings for structural problems: header names and schemes that are not HTTP
+* tokens, and two bindings claiming the same (server, header) pair. Header names compare
+* case-insensitively, as HTTP does.
+*/
+const validateBindings = (bindings) => {
+	const badHeader = bindings.find((b) => !TOKEN_RE.test(b.header));
+	if (badHeader) return Left({
+		_tag: "McpHeaderInvalid",
+		key: badHeader.key,
+		server: badHeader.server,
+		header: badHeader.header
+	});
+	const badScheme = bindings.find((b) => b.scheme !== "" && !TOKEN_RE.test(b.scheme));
+	if (badScheme) return Left({
+		_tag: "McpSchemeInvalid",
+		key: badScheme.key,
+		server: badScheme.server,
+		scheme: badScheme.scheme
+	});
+	const claims = bindings.reduce((acc, b) => {
+		const id = `${b.server}\u0000${b.header.toLowerCase()}`;
+		return {
+			...acc,
+			[id]: [...acc[id] ?? [], b]
+		};
+	}, {});
+	const clash = Object.values(claims).find((group) => group.length > 1);
+	if (clash) {
+		const first = clash[0];
+		return Left({
+			_tag: "McpHeaderDuplicate",
+			server: first.server,
+			header: first.header,
+			keys: Set$1(clash.map((b) => b.key)).toArray()
+		});
+	}
+	return Right(void 0);
+};
+/** Check every `mcp` binding in a config. Used by `envpkt validate` and the write gate. */
+const validateMcpHeaders = (config) => validateBindings(collectBindings(config));
+/**
+* Build the HTTP header object for one MCP server: every secret whose `mcp` list names
+* `server`, merged into one object. `values` is keyed by logical secret name (as in
+* `BootResult.secrets`), so namespaces and aliases are already resolved by the caller.
+* Only this server's bindings are checked, so a problem on another server never blocks it.
+*/
+const buildMcpHeaders = (config, values, server) => {
+	const matches = collectBindings(config).filter((b) => b.server === server);
+	if (matches.length === 0) return Left({
+		_tag: "McpServerUnknown",
+		server
+	});
+	return validateBindings(matches).flatMap(() => {
+		const unresolved = matches.filter((b) => !values[b.key]).map((b) => b.key);
+		if (unresolved.length > 0) return Left({
+			_tag: "McpValueUnresolved",
+			server,
+			keys: unresolved
+		});
+		const unsafe = matches.filter((b) => UNSAFE_VALUE_RE.test(values[b.key])).map((b) => b.key);
+		if (unsafe.length > 0) return Left({
+			_tag: "McpValueInvalid",
+			server,
+			keys: unsafe
+		});
+		return Right(Object.fromEntries(matches.map((b) => {
+			const value = values[b.key];
+			return [b.header, b.scheme === "" ? value : `${b.scheme} ${value}`];
+		})));
+	});
+};
+/** Human-readable one-liner for any McpHeadersError tag. Never includes a secret value. */
+const formatMcpHeadersError = (error) => {
+	switch (error._tag) {
+		case "McpHeaderInvalid": return `[secret.${error.key}] mcp server "${error.server}": header "${error.header}" is not a valid HTTP header name`;
+		case "McpSchemeInvalid": return `[secret.${error.key}] mcp server "${error.server}": scheme "${error.scheme}" must be a single word or ""`;
+		case "McpHeaderDuplicate": return `MCP server "${error.server}": header "${error.header}" is claimed by more than one binding: ${error.keys.join(", ")}`;
+		case "McpServerUnknown": return `No secret declares mcp server "${error.server}"`;
+		case "McpValueUnresolved": return `MCP server "${error.server}": no value resolved for ${error.keys.join(", ")}`;
+		case "McpValueInvalid": return `MCP server "${error.server}": value of ${error.keys.join(", ")} contains a line break or NUL and cannot be sent as a header`;
+	}
+};
+//#endregion
 //#region src/core/validate.ts
 /**
-* Validate a raw TOML string as a complete envpkt config: parse → schema → aliases.
+* Validate a raw TOML string as a complete envpkt config: parse → schema → aliases → mcp.
 *
 * Used by write-path CLI commands to verify the post-edit file would still be
 * structurally valid before persisting. Catalog resolution is intentionally
 * excluded — catalog issues depend on external files, not on the local edit,
 * and `envpkt validate` covers them as a separate explicit check.
 */
-const validateRawConfig = (raw) => parseToml(raw).flatMap(validateConfig).flatMap((config) => validateAliases(config).map(() => config));
+const validateRawConfig = (raw) => parseToml(raw).flatMap(validateConfig).flatMap((config) => validateAliases(config).map(() => config)).flatMap((config) => validateMcpHeaders(config).map(() => config));
 /** Human-readable one-liner for any ValidationError tag. */
 const formatValidationError = (err) => {
 	switch (err._tag) {
@@ -1987,6 +2114,9 @@ const formatValidationError = (err) => {
 		case "AliasChained":
 		case "AliasCrossType":
 		case "AliasValueConflict": return formatAliasError(err);
+		case "McpHeaderInvalid":
+		case "McpSchemeInvalid":
+		case "McpHeaderDuplicate": return formatMcpHeadersError(err);
 	}
 };
 //#endregion
@@ -2073,14 +2203,16 @@ const sealedSecretBlock = (key, destName, srcConfig, srcPath, destConfig) => {
 		console.error(`${RED}Error:${RESET} "${key}" produced no plaintext on unseal.`);
 		return process.exit(2);
 	}
+	const cipher = orExit(ageEncrypt(plaintext, recipient), (err) => `${RED}Error:${RESET} reseal failed for "${destName}": ${err.message}`, 2);
 	return serializeSecretBlock(destName, copyableSecretMeta(meta, {
 		today,
-		encryptedValue: Option(orExit(ageEncrypt(plaintext, recipient), (err) => `${RED}Error:${RESET} reseal failed for "${destName}": ${err.message}`, 2))
+		encryptedValue: Option(cipher)
 	}));
 };
 const writeBlock = (destPath, header, block, overwrite, dryRun, successMsg) => {
 	const raw = readFileSync(destPath, "utf-8");
-	const updated = appendSection(overwrite ? orExit(removeSection(raw, header), (err) => `${RED}Error:${RESET} ${err._tag}: ${err.section}`, 2) : raw, block);
+	const baseRaw = overwrite ? orExit(removeSection(raw, header), (err) => `${RED}Error:${RESET} ${err._tag}: ${err.section}`, 2) : raw;
+	const updated = appendSection(baseRaw, block);
 	if (dryRun) {
 		previewIfValid(updated, block);
 		return;
@@ -2121,7 +2253,8 @@ const runCopy = (key, options) => {
 		process.exit(1);
 	}
 	const block = inSecret ? sealedSecretBlock(key, destName, srcConfig, src.path, destConfig) : serializeEnvBlock(destName, srcConfig.env[key]);
-	const successMsg = `${GREEN}✓${RESET} Copied ${kindWord} ${BOLD}${key}${RESET}${destName !== key ? ` → ${BOLD}${destName}${RESET}` : ""} to ${CYAN}${dest.path}${RESET}`;
+	const renamed = destName !== key ? ` → ${BOLD}${destName}${RESET}` : "";
+	const successMsg = `${GREEN}✓${RESET} Copied ${kindWord} ${BOLD}${key}${RESET}${renamed} to ${CYAN}${dest.path}${RESET}`;
 	writeBlock(dest.path, `[${kindWord}.${destName}]`, block, existsInDest, options.dryRun === true, successMsg);
 };
 //#endregion
@@ -2906,7 +3039,8 @@ const VALUE_SHAPE_PATTERNS = [
 ];
 /** Detect service from value prefix/shape */
 const matchValueShape = (value) => {
-	return Option(VALUE_SHAPE_PATTERNS.find((vp) => value.startsWith(vp.prefix))).map((vp) => ({
+	const match = VALUE_SHAPE_PATTERNS.find((vp) => value.startsWith(vp.prefix));
+	return Option(match).map((vp) => ({
 		service: vp.service,
 		description: vp.description
 	}));
@@ -2946,7 +3080,8 @@ const matchEnvVar = (name, value) => {
 		matchedBy: `exact:${exactMatch.pattern}`
 	});
 	return matchValueShape(value).fold(() => {
-		return Option(SUFFIX_PATTERNS.find((sp) => name.endsWith(sp.suffix))).map((sp) => ({
+		const suffixMatch = SUFFIX_PATTERNS.find((sp) => name.endsWith(sp.suffix));
+		return Option(suffixMatch).map((sp) => ({
 			envVar: name,
 			value,
 			service: Option(deriveServiceFromName(name)),
@@ -3148,7 +3283,8 @@ const runEnvCheck = (options) => {
 			console.error(formatError(err));
 			process.exit(2);
 		}, (rawConfig) => {
-			resolveConfig(rawConfig, dirname(path)).fold((err) => {
+			const configDir = dirname(path);
+			resolveConfig(rawConfig, configDir).fold((err) => {
 				console.error(formatError(err));
 				process.exit(2);
 			}, (resolveResult) => {
@@ -3319,7 +3455,9 @@ const runEnvAdd = (name, value, options) => {
 				console.log(block);
 				return;
 			}
-			writeIfValid(configPath, appendSection(readFileSync(configPath, "utf-8"), block), `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
+			const raw = readFileSync(configPath, "utf-8");
+			const updated = appendSection(raw, block);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Added ${BOLD}${name}${RESET} to ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -3440,7 +3578,9 @@ const runEnvAlias = (name, options) => {
 				return;
 			}
 			const raw = readFileSync(configPath, "utf-8");
-			writeIfValid(configPath, appendSection(existing ? removeSection(raw, `[env.${name}]`).fold(() => raw, (r) => r) : raw, block), `${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+			const base = existing ? removeSection(raw, `[env.${name}]`).fold(() => raw, (r) => r) : raw;
+			const updated = appendSection(base, block);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -3565,7 +3705,7 @@ function* findEnvpktFiles(dir, maxDepth, currentDepth = 0) {
 }
 const scanFleet = (rootDir, options) => {
 	const maxDepth = options?.maxDepth ?? 3;
-	const agentList = List(Array.from(findEnvpktFiles(rootDir, maxDepth)).flatMap((configPath) => loadConfig(configPath).fold(() => [], (config) => {
+	const agents = Array.from(findEnvpktFiles(rootDir, maxDepth)).flatMap((configPath) => loadConfig(configPath).fold(() => [], (config) => {
 		const audit = computeAudit(config);
 		return [{
 			path: configPath,
@@ -3573,7 +3713,8 @@ const scanFleet = (rootDir, options) => {
 			min_expiry_days: audit.secrets.toArray().reduce((min, s) => s.days_remaining.fold(() => min, (d) => min.fold(() => Option(d), (m) => Option(Math.min(m, d)))), Option(void 0)).orUndefined(),
 			audit
 		}];
-	})));
+	}));
+	const agentList = List(agents);
 	const total_agents = agentList.size;
 	const total_secrets = agentList.toArray().reduce((acc, a) => acc + a.audit.total, 0);
 	const expired = agentList.toArray().reduce((acc, a) => acc + a.audit.expired, 0);
@@ -3599,7 +3740,8 @@ const statusIcon = (status) => {
 	}
 };
 const runFleet = (options) => {
-	const fleet = scanFleet(resolve(options.dir ?? "."), { maxDepth: options.depth });
+	const rootDir = resolve(options.dir ?? ".");
+	const fleet = scanFleet(rootDir, { maxDepth: options.depth });
 	if (options.format === "json") {
 		console.log(formatFleetJson(fleet));
 		process.exit(fleet.status === "critical" ? 2 : 0);
@@ -3618,6 +3760,36 @@ const runFleet = (options) => {
 	process.exit(fleet.status === "critical" ? 2 : 0);
 };
 //#endregion
+//#region src/cli/commands/headers.ts
+const SERVER_ENV = "CLAUDE_CODE_MCP_SERVER_NAME";
+/**
+* Claude Code `headersHelper` entry point: print the HTTP headers for one MCP server as a
+* JSON object. stdout carries the JSON and nothing else; every diagnostic goes to stderr,
+* because Claude parses stdout verbatim.
+*/
+const runHeaders = (serverArg, options) => {
+	const server = serverArg ?? process.env[SERVER_ENV];
+	if (!server) {
+		console.error(`${RED}Error:${RESET} No MCP server named. Pass [server] or set ${SERVER_ENV}.`);
+		process.exit(2);
+	}
+	resolveForEmit(options).fold((err) => {
+		console.error(`MCP server "${server}":\n${formatError(err)}`);
+		process.exit(2);
+	}, (boot) => {
+		emitWarnings(boot);
+		loadConfig(boot.configPath).flatMap((config) => resolveConfig(config, dirname(boot.configPath)).map((r) => r.config)).fold((err) => {
+			console.error(`MCP server "${server}":\n${formatError(err)}`);
+			return process.exit(2);
+		}, (config) => buildMcpHeaders(config, boot.secrets, server)).fold((err) => {
+			console.error(`${RED}Error:${RESET} ${formatMcpHeadersError(err)}`);
+			process.exit(1);
+		}, (map) => {
+			process.stdout.write(`${JSON.stringify(map)}\n`);
+		});
+	});
+};
+//#endregion
 //#region src/cli/commands/init.ts
 const CONFIG_FILENAME = "envpkt.toml";
 /** Resolve the top-level `scope` to scaffold: explicit --scope wins; --global implies "shell". */
@@ -3893,7 +4065,8 @@ const deriveKeyPath = (configPath) => {
 };
 const runKeygen = (options) => {
 	const configPath = resolve(options.config ?? join(process.cwd(), "envpkt.toml"));
-	generateKeypair({ outputPath: options.output ?? (options.global ? resolveKeyPath() : deriveKeyPath(configPath)) }).fold((err) => {
+	const outputPath = options.output ?? (options.global ? resolveKeyPath() : deriveKeyPath(configPath));
+	generateKeypair({ outputPath }).fold((err) => {
 		if (err._tag === "KeyExists") {
 			console.error(`${YELLOW}Warning:${RESET} Identity file already exists: ${CYAN}${err.path}${RESET}`);
 			console.error(`${DIM}To replace it: remove the file first, then re-run keygen.${RESET}`);
@@ -4263,7 +4436,8 @@ const runResolve = (options) => {
 			console.error(formatError(err));
 			process.exit(2);
 		}, (config) => {
-			resolveConfig(config, dirname(configPath)).fold((err) => {
+			const configDir = dirname(configPath);
+			resolveConfig(config, configDir).fold((err) => {
 				console.error(formatError(err));
 				process.exit(2);
 			}, (result) => {
@@ -4490,7 +4664,8 @@ const runSeal = async (options) => {
 		process.exit(2);
 	}
 	const identityKey = Option(config.identity.key_file).flatMap((keyFile) => {
-		return unwrapAgentKey(resolve(configDir, expandPath(keyFile))).fold((err) => {
+		const identityPath = resolve(configDir, expandPath(keyFile));
+		return unwrapAgentKey(identityPath).fold((err) => {
 			const msg = err._tag === "IdentityNotFound" ? `not found: ${err.path}` : err.message;
 			console.error(`${YELLOW}Warning:${RESET} Could not unwrap agent key: ${msg}`);
 			return Option.none();
@@ -4586,7 +4761,8 @@ const runSeal = async (options) => {
 				console.error(`${DIM}  3. ~/.envpkt/age-key.txt${RESET}`);
 				process.exit(2);
 			}
-			const decrypted = unsealSecrets(Object.fromEntries(alreadySealed.map((k) => [k, allSecretEntries[k]])), identityPath).fold((err) => {
+			const sealedEntries = Object.fromEntries(alreadySealed.map((k) => [k, allSecretEntries[k]]));
+			const decrypted = unsealSecrets(sealedEntries, identityPath).fold((err) => {
 				console.error(`${RED}Error:${RESET} Failed to decrypt existing secrets: ${err.message}`);
 				process.exit(2);
 				return {};
@@ -4723,7 +4899,8 @@ const runSecretAdd = (name, options) => {
 				process.exit(1);
 			}
 			const block = buildSecretBlock(name, options);
-			const updated = appendSection(readFileSync(configPath, "utf-8"), block);
+			const raw = readFileSync(configPath, "utf-8");
+			const updated = appendSection(raw, block);
 			if (options.dryRun) {
 				previewIfValid(updated, block);
 				return;
@@ -4864,7 +5041,9 @@ const runSecretAlias = (name, options) => {
 				return;
 			}
 			const raw = readFileSync(configPath, "utf-8");
-			writeIfValid(configPath, appendSection(existing ? removeSection(raw, `[secret.${name}]`).fold(() => raw, (r) => r) : raw, block), `${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
+			const base = existing ? removeSection(raw, `[secret.${name}]`).fold(() => raw, (r) => r) : raw;
+			const updated = appendSection(base, block);
+			writeIfValid(configPath, updated, `${GREEN}✓${RESET} Aliased ${BOLD}${name}${RESET} → ${BOLD}${options.from}${RESET} in ${CYAN}${configPath}${RESET}`);
 		});
 	});
 };
@@ -4947,7 +5126,8 @@ const runSecretRotate = async (name, options) => {
 		process.exit(2);
 		return "";
 	}, (ct) => ct);
-	updateSectionFields(applySealedToml(raw, { [name]: { encrypted_value: ciphertext } }), `[secret.${name}]`, { last_rotated_at: `"${today}"` }).fold((err) => {
+	const withSealed = applySealedToml(raw, { [name]: { encrypted_value: ciphertext } });
+	updateSectionFields(withSealed, `[secret.${name}]`, { last_rotated_at: `"${today}"` }).fold((err) => {
 		console.error(`${RED}Error:${RESET} ${err._tag}: ${err.section}`);
 		process.exit(2);
 	}, (result) => {
@@ -5182,6 +5362,7 @@ const CHECK_NAMES = {
 	schema: "Schema",
 	catalog: "Catalog",
 	aliases: "Aliases",
+	mcp: "MCP headers",
 	sealed: "Sealed blocks"
 };
 /** Structural sanity scan over each [secret.*].encrypted_value PEM block. No decryption. */
@@ -5210,6 +5391,24 @@ const checkSealedBlocks = (config) => {
 		error: broken.join("; ")
 	};
 };
+/** `mcp` bindings: valid header names and schemes, no (server, header) pair claimed twice. */
+const checkMcpHeaders = (config) => {
+	const count = Object.values(config.secret ?? {}).reduce((n, meta) => n + (meta.mcp?.length ?? 0), 0);
+	if (count === 0) return {
+		name: CHECK_NAMES.mcp,
+		status: "na",
+		detail: "no mcp bindings"
+	};
+	return validateMcpHeaders(config).fold((err) => ({
+		name: CHECK_NAMES.mcp,
+		status: "failed",
+		error: formatValidationError(err)
+	}), () => ({
+		name: CHECK_NAMES.mcp,
+		status: "ok",
+		detail: `${count} binding(s)`
+	}));
+};
 const skipped = (name) => ({
 	name,
 	status: "skipped"
@@ -5227,6 +5426,7 @@ const buildReport = (path, raw) => {
 			skipped(CHECK_NAMES.schema),
 			skipped(CHECK_NAMES.catalog),
 			skipped(CHECK_NAMES.aliases),
+			skipped(CHECK_NAMES.mcp),
 			skipped(CHECK_NAMES.sealed)
 		]
 	}), (data) => {
@@ -5246,6 +5446,7 @@ const buildReport = (path, raw) => {
 				},
 				skipped(CHECK_NAMES.catalog),
 				skipped(CHECK_NAMES.aliases),
+				skipped(CHECK_NAMES.mcp),
 				skipped(CHECK_NAMES.sealed)
 			]
 		}), (config) => {
@@ -5275,12 +5476,15 @@ const buildReport = (path, raw) => {
 				status: "ok",
 				detail: `${table.entries.size} alias(es)`
 			}));
+			const merged = config.catalog ? resolveConfig(config, dirname(path)).fold(() => config, (r) => r.config) : config;
+			const mcpCheck = checkMcpHeaders(merged);
 			const sealedCheck = checkSealedBlocks(config);
 			const checks = [
 				tomlOk,
 				schemaOk,
 				catalogCheck,
 				aliasCheck,
+				mcpCheck,
 				sealedCheck
 			];
 			return {
@@ -5303,7 +5507,9 @@ const renderCheckLines = (check) => {
 	}
 };
 const formatTextReport = (report, sourceMsg) => {
-	const header = `${report.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`} ${BOLD}${report.ok ? `${GREEN}VALID${RESET}` : `${RED}INVALID${RESET}`}${RESET} — ${CYAN}${report.configPath}${RESET}`;
+	const headerIcon = report.ok ? `${GREEN}✓${RESET}` : `${RED}✗${RESET}`;
+	const headerLabel = report.ok ? `${GREEN}VALID${RESET}` : `${RED}INVALID${RESET}`;
+	const header = `${headerIcon} ${BOLD}${headerLabel}${RESET} — ${CYAN}${report.configPath}${RESET}`;
 	const checkLines = report.checks.flatMap((c) => [...renderCheckLines(c)]);
 	return [
 		...sourceMsg ? [sourceMsg] : [],
@@ -5388,7 +5594,7 @@ program.command("audit").description("Audit credential health from envpkt.toml (
 program.command("fleet").description("Scan directory tree for envpkt.toml files and aggregate health (use in CI for fleet-wide monitoring)").option("-d, --dir <path>", "Root directory to scan", ".").option("--depth <n>", "Max directory depth", parseInt).option("--format <format>", "Output format: table | json", "table").option("--status <status>", "Filter agents by health status").action((options) => {
 	runFleet(options);
 });
-program.command("validate").description("Verify envpkt.toml integrity — runs TOML syntax, schema, catalog, alias, and sealed-block structural checks").option("-c, --config <path>", "Path to envpkt.toml").option("--json", "Output structured JSON instead of human-readable text").action((options) => {
+program.command("validate").description("Verify envpkt.toml integrity — runs TOML syntax, schema, catalog, alias, MCP header, and sealed-block structural checks").option("-c, --config <path>", "Path to envpkt.toml").option("--json", "Output structured JSON instead of human-readable text").action((options) => {
 	runValidate(options);
 });
 program.command("inspect").description("Display structured view of envpkt.toml").option("-c, --config <path>", "Path to envpkt.toml").option("--format <format>", "Output format: table | json", "table").option("--resolved", "Show resolved view (catalog merged)").option("--secrets", "Show secret values from environment (masked by default)").option("--plaintext", "Show secret values in plaintext (requires --secrets)").option("--sort", "Display secrets and env entries in alphabetical order (no file mutation)").action((options) => {
@@ -5397,6 +5603,9 @@ program.command("inspect").description("Display structured view of envpkt.toml")
 program.command("exec").description("Run pre-flight audit then execute a command with injected secrets (sealed → fnox → env cascade)").argument("<command...>", "Command to execute").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").option("--skip-audit", "Skip the pre-flight audit (alias: --no-check)").option("--no-check", "Skip the pre-flight audit").option("--warn-only", "Warn on critical audit but do not abort").option("--strict", "Abort on any non-healthy secret").action((args, options) => {
 	runExec(args, options);
 });
+program.command("headers").description("Print HTTP headers for an MCP server as JSON — for Claude Code's headersHelper in .mcp.json").argument("[server]", "MCP server name (default: $CLAUDE_CODE_MCP_SERVER_NAME)").option("-c, --config <path>", "Path to envpkt.toml").option("--profile <profile>", "fnox profile to use").action((server, options) => {
+	runHeaders(server, options);
+});
 program.command("resolve").description("Resolve catalog references and output a flat, self-contained config").option("-c, --config <path>", "Path to envpkt.toml").option("-o, --output <path>", "Write resolved config to file (default: stdout)").option("--format <format>", "Output format: toml | json", "toml").option("--dry-run", "Show what would be resolved without writing").action((options) => {
 	runResolve(options);
 });

package/dist/index.d.ts

@@ -31,6 +31,12 @@ declare const AgentIdentitySchema: import("@sinclair/typebox").TObject<{
   recipient: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   secrets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
 }>;
+declare const McpHeaderSchema: import("@sinclair/typebox").TObject<{
+  server: import("@sinclair/typebox").TString;
+  header: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  scheme: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+type McpHeader = Static<typeof McpHeaderSchema>;
 declare const SecretMetaSchema: import("@sinclair/typebox").TObject<{
   service: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
   expires: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -50,6 +56,11 @@ declare const SecretMetaSchema: import("@sinclair/typebox").TObject<{
   external: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
   tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
   namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  mcp: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+    server: import("@sinclair/typebox").TString;
+    header: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    scheme: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+  }>>>;
 }>;
 type SecretMeta = Static<typeof SecretMetaSchema>;
 declare const LifecycleConfigSchema: import("@sinclair/typebox").TObject<{
@@ -113,6 +124,11 @@ declare const EnvpktConfigSchema: import("@sinclair/typebox").TObject<{
     external: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     tags: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TString>>;
     namespace: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    mcp: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+      server: import("@sinclair/typebox").TString;
+      header: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+      scheme: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>>;
   }>>>;
   env: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
     value: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
@@ -299,6 +315,35 @@ type AliasError = {
   readonly kind: "secret" | "env";
   readonly field: string;
 };
+/** Structural problems in `mcp` bindings — caught by validation, independent of secret values. */
+type McpConfigError = {
+  readonly _tag: "McpHeaderInvalid";
+  readonly key: string;
+  readonly server: string;
+  readonly header: string;
+} | {
+  readonly _tag: "McpSchemeInvalid";
+  readonly key: string;
+  readonly server: string;
+  readonly scheme: string;
+} | {
+  readonly _tag: "McpHeaderDuplicate";
+  readonly server: string;
+  readonly header: string;
+  readonly keys: ReadonlyArray<string>;
+};
+type McpHeadersError = McpConfigError | {
+  readonly _tag: "McpServerUnknown";
+  readonly server: string;
+} | {
+  readonly _tag: "McpValueUnresolved";
+  readonly server: string;
+  readonly keys: ReadonlyArray<string>;
+} | {
+  readonly _tag: "McpValueInvalid";
+  readonly server: string;
+  readonly keys: ReadonlyArray<string>;
+};
 type BootOptions = {
   readonly configPath?: string;
   readonly profile?: string;
@@ -447,6 +492,19 @@ declare const isEnvAlias: (meta: {
 /** Format an alias error into a human-readable message */
 declare const formatAliasError: (error: AliasError) => string;
 //#endregion
+//#region src/core/mcp-headers.d.ts
+/** Check every `mcp` binding in a config. Used by `envpkt validate` and the write gate. */
+declare const validateMcpHeaders: (config: EnvpktConfig) => Either<McpConfigError, void>;
+/**
+ * Build the HTTP header object for one MCP server: every secret whose `mcp` list names
+ * `server`, merged into one object. `values` is keyed by logical secret name (as in
+ * `BootResult.secrets`), so namespaces and aliases are already resolved by the caller.
+ * Only this server's bindings are checked, so a problem on another server never blocks it.
+ */
+declare const buildMcpHeaders: (config: EnvpktConfig, values: Readonly<Record<string, string>>, server: string) => Either<McpHeadersError, Record<string, string>>;
+/** Human-readable one-liner for any McpHeadersError tag. Never includes a secret value. */
+declare const formatMcpHeadersError: (error: McpHeadersError) => string;
+//#endregion
 //#region src/core/format.d.ts
 type SecretDisplay = "encrypted" | "plaintext";
 type FormatPacketOptions = {
@@ -721,4 +779,4 @@ type ToolDef = {
 declare const toolDefinitions: readonly ToolDef[];
 declare const callTool: (name: string, args: Record<string, unknown>) => CallToolResult;
 //#endregion
-export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type ChangedEntry, type CheckResult, type ConfidenceLevel, type ConfigDiff, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DotenvEntry, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FieldChange, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatDotenvOptions, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type SectionDiff, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, copyableSecretMeta, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, diffConfigs, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, serializeEnvBlock, serializeSecretBlock, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { type AgentIdentity, AgentIdentitySchema, type AliasError, type AliasTable, type AuditResult, type BootError, type BootOptions, type BootResult, type CallbackConfig, CallbackConfigSchema, type CatalogError, type ChangedEntry, type CheckResult, type ConfidenceLevel, type ConfigDiff, type ConfigError, type ConfigSource, ConsumerType, type CredentialPattern, type DirectLogger, type DirectTestLoggerHandle, type DotenvEntry, type DriftEntry, type DriftStatus, type EnvAuditResult, type EnvDriftEntry, type EnvDriftStatus, type EnvMeta, EnvMetaSchema, EnvpktBootError, type EnvpktConfig, EnvpktConfigSchema, type FieldChange, type FleetAgent, type FleetHealth, type FnoxConfig, type FnoxError, type FnoxSecret, type FormatDotenvOptions, type FormatPacketOptions, type HealthStatus, type Identity, type IdentityError, IdentitySchema, type KeygenError, type KeygenResult, type LifecycleConfig, LifecycleConfigSchema, type LogEntry, type LogLevel, type LogMetadata, type MatchResult, type McpConfigError, type McpHeader, McpHeaderSchema, type McpHeadersError, type ResolveOptions, type ResolveResult, type ResolvedPath, type ScanOptions, type ScanResult, type SealError, type SecretDisplay, type SecretHealth, type SecretMeta, SecretMetaSchema, type SecretStatus, type SectionDiff, type TomlEditError, type ToolsConfig, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, buildMcpHeaders, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, copyableSecretMeta, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, diffConfigs, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatMcpHeadersError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, serializeEnvBlock, serializeSecretBlock, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig, validateMcpHeaders };

package/dist/index.js

@@ -46,6 +46,21 @@ const NamespaceSchema = Type.Object({
 		description: "Separator between prefix and key. Default '__' (shell-safe). Note: '.' and ':' are not valid in shell identifiers."
 	}))
 }, { description: "Optional namespace/package prefix for injected environment variable names" });
+const McpHeaderSchema = Type.Object({
+	server: Type.String({
+		minLength: 1,
+		description: "MCP server name, as keyed in .mcp.json"
+	}),
+	header: Type.Optional(Type.String({
+		default: "Authorization",
+		minLength: 1,
+		description: "HTTP header name to send the secret in"
+	})),
+	scheme: Type.Optional(Type.String({
+		default: "Bearer",
+		description: "Prefix placed before the value (e.g. 'Bearer'). Empty string sends the raw value."
+	}))
+}, { description: "Send this secret as an HTTP header to an MCP server" });
 const SecretMetaSchema = Type.Object({
 	service: Type.Optional(Type.String({ description: "Service or system this secret authenticates to" })),
 	expires: Type.Optional(Type.String({
@@ -76,7 +91,8 @@ const SecretMetaSchema = Type.Object({
 	required: Type.Optional(Type.Boolean({ description: "Whether this secret is required for operation" })),
 	external: Type.Optional(Type.Boolean({ description: "Value is managed outside envpkt (e.g. a Cloudflare/Vault secret). The entry registers the name for inventory and dev/prod parity only: seal never touches it, and audit reports it as 'external' rather than 'missing'." })),
 	tags: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Key-value tags for grouping and filtering" })),
-	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." }))
+	namespace: Type.Optional(Type.String({ description: "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix." })),
+	mcp: Type.Optional(Type.Array(McpHeaderSchema, { description: "MCP servers this secret authenticates to. Read by `envpkt headers` (Claude Code headersHelper)." }))
 }, { description: "Metadata about a single secret" });
 const LifecycleConfigSchema = Type.Object({
 	stale_warning_days: Type.Optional(Type.Number({
@@ -209,10 +225,13 @@ const discoverConfig = (cwd) => {
 		template,
 		expanded: expandPath(template)
 	})).filter(({ expanded }) => expanded !== "" && !expanded.startsWith("/.envpkt")).map(({ expanded }) => expandGlobPath(expanded)).find((matches) => matches.length > 0);
-	if (customMatch) return Option({
-		path: customMatch[0],
-		source: "search"
-	});
+	if (customMatch) {
+		const found = {
+			path: customMatch[0],
+			source: "search"
+		};
+		return Option(found);
+	}
 	const platformMatch = buildSearchPaths().find((p) => Fs.existsSync(p));
 	if (platformMatch) return Option({
 		path: platformMatch,
@@ -254,9 +273,10 @@ const parseToml = (raw) => Try(() => parse(raw)).fold((err) => Left({
 /** Validate parsed data against the TypeBox schema */
 const validateConfig = (data) => {
 	if (compiledSchema.Check(data)) return Right(data);
+	const errors = List([...compiledSchema.Errors(data)].map((e) => `${e.path}: ${e.message}`));
 	return Left({
 		_tag: "ValidationError",
-		errors: List([...compiledSchema.Errors(data)].map((e) => `${e.path}: ${e.message}`))
+		errors
 	});
 };
 /** Load and validate an envpkt.toml from a file path */
@@ -505,6 +525,104 @@ const formatAliasError = (error) => {
 	}
 };
 //#endregion
+//#region src/core/mcp-headers.ts
+const DEFAULT_HEADER = "Authorization";
+const DEFAULT_SCHEME = "Bearer";
+/** RFC 9110 `token`: the legal characters of a header name (and of an auth scheme). */
+const TOKEN_RE = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+/** Characters that would split or corrupt an HTTP header value. */
+const UNSAFE_VALUE_RE = /[\r\n\0]/;
+/** Flatten every `[secret.*].mcp` entry into one binding per (secret, server), with defaults applied. */
+const collectBindings = (config) => Object.entries(config.secret ?? {}).flatMap(([key, meta]) => (meta.mcp ?? []).map((m) => ({
+	key,
+	server: m.server,
+	header: m.header ?? DEFAULT_HEADER,
+	scheme: m.scheme ?? DEFAULT_SCHEME
+})));
+/**
+* Check bindings for structural problems: header names and schemes that are not HTTP
+* tokens, and two bindings claiming the same (server, header) pair. Header names compare
+* case-insensitively, as HTTP does.
+*/
+const validateBindings = (bindings) => {
+	const badHeader = bindings.find((b) => !TOKEN_RE.test(b.header));
+	if (badHeader) return Left({
+		_tag: "McpHeaderInvalid",
+		key: badHeader.key,
+		server: badHeader.server,
+		header: badHeader.header
+	});
+	const badScheme = bindings.find((b) => b.scheme !== "" && !TOKEN_RE.test(b.scheme));
+	if (badScheme) return Left({
+		_tag: "McpSchemeInvalid",
+		key: badScheme.key,
+		server: badScheme.server,
+		scheme: badScheme.scheme
+	});
+	const claims = bindings.reduce((acc, b) => {
+		const id = `${b.server}\u0000${b.header.toLowerCase()}`;
+		return {
+			...acc,
+			[id]: [...acc[id] ?? [], b]
+		};
+	}, {});
+	const clash = Object.values(claims).find((group) => group.length > 1);
+	if (clash) {
+		const first = clash[0];
+		return Left({
+			_tag: "McpHeaderDuplicate",
+			server: first.server,
+			header: first.header,
+			keys: Set$1(clash.map((b) => b.key)).toArray()
+		});
+	}
+	return Right(void 0);
+};
+/** Check every `mcp` binding in a config. Used by `envpkt validate` and the write gate. */
+const validateMcpHeaders = (config) => validateBindings(collectBindings(config));
+/**
+* Build the HTTP header object for one MCP server: every secret whose `mcp` list names
+* `server`, merged into one object. `values` is keyed by logical secret name (as in
+* `BootResult.secrets`), so namespaces and aliases are already resolved by the caller.
+* Only this server's bindings are checked, so a problem on another server never blocks it.
+*/
+const buildMcpHeaders = (config, values, server) => {
+	const matches = collectBindings(config).filter((b) => b.server === server);
+	if (matches.length === 0) return Left({
+		_tag: "McpServerUnknown",
+		server
+	});
+	return validateBindings(matches).flatMap(() => {
+		const unresolved = matches.filter((b) => !values[b.key]).map((b) => b.key);
+		if (unresolved.length > 0) return Left({
+			_tag: "McpValueUnresolved",
+			server,
+			keys: unresolved
+		});
+		const unsafe = matches.filter((b) => UNSAFE_VALUE_RE.test(values[b.key])).map((b) => b.key);
+		if (unsafe.length > 0) return Left({
+			_tag: "McpValueInvalid",
+			server,
+			keys: unsafe
+		});
+		return Right(Object.fromEntries(matches.map((b) => {
+			const value = values[b.key];
+			return [b.header, b.scheme === "" ? value : `${b.scheme} ${value}`];
+		})));
+	});
+};
+/** Human-readable one-liner for any McpHeadersError tag. Never includes a secret value. */
+const formatMcpHeadersError = (error) => {
+	switch (error._tag) {
+		case "McpHeaderInvalid": return `[secret.${error.key}] mcp server "${error.server}": header "${error.header}" is not a valid HTTP header name`;
+		case "McpSchemeInvalid": return `[secret.${error.key}] mcp server "${error.server}": scheme "${error.scheme}" must be a single word or ""`;
+		case "McpHeaderDuplicate": return `MCP server "${error.server}": header "${error.header}" is claimed by more than one binding: ${error.keys.join(", ")}`;
+		case "McpServerUnknown": return `No secret declares mcp server "${error.server}"`;
+		case "McpValueUnresolved": return `MCP server "${error.server}": no value resolved for ${error.keys.join(", ")}`;
+		case "McpValueInvalid": return `MCP server "${error.server}": value of ${error.keys.join(", ")} contains a line break or NUL and cannot be sent as a header`;
+	}
+};
+//#endregion
 //#region src/core/format.ts
 const maskValue = (value) => {
 	if (value.length > 8) return `${value.slice(0, 3)}${"•".repeat(5)}${value.slice(-4)}`;
@@ -690,14 +808,15 @@ const computeAudit = (config, fnoxKeys, today, aliasTable) => {
 	const staleWarningDays = lifecycle.stale_warning_days ?? 90;
 	const requireExpiration = lifecycle.require_expiration ?? false;
 	const requireService = lifecycle.require_service ?? false;
-	const keys = fnoxKeys ?? /* @__PURE__ */ new Set();
+	const keys = fnoxKeys ?? Set$1.empty();
 	const secretEntries = config.secret ?? {};
 	const nonAliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key === void 0);
 	const aliasEntries = Object.entries(secretEntries).filter(([, meta]) => meta.from_key !== void 0);
 	const nonAliasHealth = nonAliasEntries.map(([key, meta]) => classifySecret(key, meta, keys, staleWarningDays, requireExpiration, requireService, now));
 	const healthByKey = Map$1(nonAliasHealth.map((h) => [h.key, h]));
 	const parseTargetKey = (from_key) => {
-		return Option(from_key.match(/^secret\.(.+)$/)?.[1]);
+		const match = from_key.match(/^secret\.(.+)$/);
+		return Option(match?.[1]);
 	};
 	const aliasHealth = aliasEntries.map(([key, meta]) => {
 		const tableEntry = aliasTable?.entries.get(`secret.${key}`);
@@ -751,8 +870,10 @@ const computeEnvAudit = (config, env = process.env) => {
 	const envWire = (key) => namer(key, envEntries[key]?.namespace);
 	const resolveEffectiveDefault = (entry) => {
 		return Do(function* () {
-			const targetKey = yield* $(Option((yield* $(Option(entry.from_key))).match(/^env\.(.+)$/)?.[1]));
-			return yield* $(Option((yield* $(Option(envEntries[targetKey]))).value));
+			const fk = yield* $(Option(entry.from_key));
+			const targetKey = yield* $(Option(fk.match(/^env\.(.+)$/)?.[1]));
+			const targetEntry = yield* $(Option(envEntries[targetKey]));
+			return yield* $(Option(targetEntry.value));
 		}).orElse(entry.value ?? "");
 	};
 	const entries = Object.entries(envEntries).map(([key, entry]) => {
@@ -1398,7 +1519,8 @@ const VALUE_SHAPE_PATTERNS = [
 ];
 /** Detect service from value prefix/shape */
 const matchValueShape = (value) => {
-	return Option(VALUE_SHAPE_PATTERNS.find((vp) => value.startsWith(vp.prefix))).map((vp) => ({
+	const match = VALUE_SHAPE_PATTERNS.find((vp) => value.startsWith(vp.prefix));
+	return Option(match).map((vp) => ({
 		service: vp.service,
 		description: vp.description
 	}));
@@ -1438,7 +1560,8 @@ const matchEnvVar = (name, value) => {
 		matchedBy: `exact:${exactMatch.pattern}`
 	});
 	return matchValueShape(value).fold(() => {
-		return Option(SUFFIX_PATTERNS.find((sp) => name.endsWith(sp.suffix))).map((sp) => ({
+		const suffixMatch = SUFFIX_PATTERNS.find((sp) => name.endsWith(sp.suffix));
+		return Option(suffixMatch).map((sp) => ({
 			envVar: name,
 			value,
 			service: Option(deriveServiceFromName(name)),
@@ -2075,7 +2198,8 @@ const bootSafe = (options) => {
 			_tag: "ReadError",
 			message: "unexpected"
 		}));
-		const audit = computeAudit(config, detectFnoxKeys(configDir), void 0, aliasTable);
+		const fnoxKeys = detectFnoxKeys(configDir);
+		const audit = computeAudit(config, fnoxKeys, void 0, aliasTable);
 		const sealIdentity = hasSealedValues ? resolveSealIdentity(config, configDir) : Option(void 0);
 		if (hasSealedValues && sealIdentity.isEmpty) return Left({
 			_tag: "SealKeyUnavailable",
@@ -2117,37 +2241,39 @@ const bootSafe = (options) => {
 				}
 			});
 			const remainingKeys = nonAliasMetaKeys.filter((k) => !sealedKeys.has(k));
-			if (remainingKeys.length > 0) if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
-				log.warn("phase.fnox.export_failed", {
-					message: err.message,
-					skipped: remainingKeys.length
-				});
-				warnings.push(`fnox export failed: ${err.message}`);
-				skipped.push(...remainingKeys);
-			}, (exported) => {
-				const found = remainingKeys.filter((key) => key in exported);
-				const notFound = remainingKeys.filter((key) => !(key in exported));
-				found.forEach((key) => {
-					secrets[key] = exported[key];
-					log.debug("phase.fnox.resolved", {
-						key,
-						profile: opts.profile
+			if (remainingKeys.length > 0) {
+				if (fnoxAvailable()) fnoxExport(opts.profile, identityKey.orUndefined()).fold((err) => {
+					log.warn("phase.fnox.export_failed", {
+						message: err.message,
+						skipped: remainingKeys.length
 					});
-				});
-				notFound.forEach((key) => {
-					log.debug("phase.fnox.not_in_export", {
-						key,
-						profile: opts.profile
+					warnings.push(`fnox export failed: ${err.message}`);
+					skipped.push(...remainingKeys);
+				}, (exported) => {
+					const found = remainingKeys.filter((key) => key in exported);
+					const notFound = remainingKeys.filter((key) => !(key in exported));
+					found.forEach((key) => {
+						secrets[key] = exported[key];
+						log.debug("phase.fnox.resolved", {
+							key,
+							profile: opts.profile
+						});
+					});
+					notFound.forEach((key) => {
+						log.debug("phase.fnox.not_in_export", {
+							key,
+							profile: opts.profile
+						});
 					});
+					injected.push(...found);
+					skipped.push(...notFound);
 				});
-				injected.push(...found);
-				skipped.push(...notFound);
-			});
-			else {
-				log.debug("phase.fnox.unavailable", { skipped: remainingKeys.length });
-				if (!hasSealedValues) warnings.push("fnox not available — no secrets injected");
-				else warnings.push("fnox not available — unsealed secrets could not be resolved");
-				skipped.push(...remainingKeys);
+				else {
+					log.debug("phase.fnox.unavailable", { skipped: remainingKeys.length });
+					if (!hasSealedValues) warnings.push("fnox not available — no secrets injected");
+					else warnings.push("fnox not available — unsealed secrets could not be resolved");
+					skipped.push(...remainingKeys);
+				}
 			}
 			aliasSecretKeys.forEach((aliasKey) => {
 				const entry = aliasTable.entries.get(`secret.${aliasKey}`);
@@ -2584,7 +2710,7 @@ function* findEnvpktFiles(dir, maxDepth, currentDepth = 0) {
 }
 const scanFleet = (rootDir, options) => {
 	const maxDepth = options?.maxDepth ?? 3;
-	const agentList = List(Array.from(findEnvpktFiles(rootDir, maxDepth)).flatMap((configPath) => loadConfig(configPath).fold(() => [], (config) => {
+	const agents = Array.from(findEnvpktFiles(rootDir, maxDepth)).flatMap((configPath) => loadConfig(configPath).fold(() => [], (config) => {
 		const audit = computeAudit(config);
 		return [{
 			path: configPath,
@@ -2592,7 +2718,8 @@ const scanFleet = (rootDir, options) => {
 			min_expiry_days: audit.secrets.toArray().reduce((min, s) => s.days_remaining.fold(() => min, (d) => min.fold(() => Option(d), (m) => Option(Math.min(m, d)))), Option(void 0)).orUndefined(),
 			audit
 		}];
-	})));
+	}));
+	const agentList = List(agents);
 	const total_agents = agentList.size;
 	const total_secrets = agentList.toArray().reduce((acc, a) => acc + a.audit.total, 0);
 	const expired = agentList.toArray().reduce((acc, a) => acc + a.audit.expired, 0);
@@ -2929,4 +3056,4 @@ const startServer = async () => {
 	await server.connect(transport);
 };
 //#endregion
-export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, copyableSecretMeta, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, diffConfigs, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, serializeEnvBlock, serializeSecretBlock, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig };
+export { AgentIdentitySchema, CallbackConfigSchema, ConsumerType, EnvMetaSchema, EnvpktBootError, EnvpktConfigSchema, IdentitySchema, LifecycleConfigSchema, McpHeaderSchema, SecretMetaSchema, ToolsConfigSchema, ageAvailable, ageDecrypt, ageEncrypt, appendSection, boot, bootSafe, buildMcpHeaders, callTool, compareFnoxAndEnvpkt, computeAudit, computeEnvAudit, copyableSecretMeta, createDirectConsoleLogger, createDirectTestLogger, createServer, deriveServiceFromName, detectFnox, diffConfigs, directSilentLogger, discoverConfig, envCheck, envScan, extractFnoxKeys, findConfigPath, fnoxAvailable, fnoxExport, fnoxGet, formatAliasError, formatDotenv, formatMcpHeadersError, formatPacket, generateKeypair, generateTomlFromScan, isEnvAlias, isSecretAlias, loadCatalog, loadConfig, loadConfigFromCwd, maskValue, matchEnvVar, matchValueShape, parseToml, quoteDotenvValue, readConfigFile, readFnoxConfig, readResource, removeSection, renameSection, resolveConfig, resolveConfigPath, resolveInlineKey, resolveKeyPath, resolveSecrets, resolveValues, resourceDefinitions, scanEnv, scanFleet, sealSecrets, serializeEnvBlock, serializeSecretBlock, startServer, toolDefinitions, unsealSecrets, unwrapAgentKey, updateConfigIdentity, updateSectionFields, validateAliases, validateConfig, validateMcpHeaders };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "envpkt",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "Credential lifecycle and fleet management for AI agents",
   "keywords": [
     "credentials",
@@ -39,19 +39,19 @@
     "prepublishOnly": "pnpm validate"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.32.0",
     "@sinclair/typebox": "^0.34.52",
     "commander": "^15.0.0",
-    "functype": "^1.8.0",
-    "functype-log": "^1.8.0",
-    "functype-os": "^1.8.0",
-    "smol-toml": "^1.7.1"
+    "functype": "^1.13.0",
+    "functype-log": "^1.13.0",
+    "functype-os": "^1.13.0",
+    "smol-toml": "^1.9.0"
   },
   "devDependencies": {
-    "@types/node": "^24.13.3",
-    "ts-builds": "^3.2.3",
+    "@types/node": "^24.19.1",
+    "ts-builds": "^3.4.3",
     "tsdown": "^0.22.14",
-    "tsx": "^4.23.1"
+    "tsx": "^4.23.15"
   },
   "type": "module",
   "main": "./dist/index.js",
@@ -71,5 +71,5 @@
     "schemas"
   ],
   "prettier": "ts-builds/prettier",
-  "packageManager": "pnpm@11.18.0+sha512.33d83c77da82f49fba836925c6f1b841181ec3132b670639bd012f7075f5c7cf634c5f870147c19aae7478fac01df09d8892e880454896edd23ee9b33757563c"
+  "packageManager": "pnpm@11.27.0+sha512.ad12821463bb143295f1fa3ecde77a6b9b97a7990386da800ff57bffc3964dc64b7b1c7559d5dbe5c337aea659ed9c8937d4370bd198ca2009bc6fa0249808e7"
 }

package/schemas/envpkt.schema.json

@@ -211,6 +211,35 @@
             "namespace": {
               "description": "Override the file-level namespace for this entry's injected name. Empty string opts out of any prefix.",
               "type": "string"
+            },
+            "mcp": {
+              "description": "MCP servers this secret authenticates to. Read by `envpkt headers` (Claude Code headersHelper).",
+              "type": "array",
+              "items": {
+                "description": "Send this secret as an HTTP header to an MCP server",
+                "type": "object",
+                "required": [
+                  "server"
+                ],
+                "properties": {
+                  "server": {
+                    "minLength": 1,
+                    "description": "MCP server name, as keyed in .mcp.json",
+                    "type": "string"
+                  },
+                  "header": {
+                    "default": "Authorization",
+                    "minLength": 1,
+                    "description": "HTTP header name to send the secret in",
+                    "type": "string"
+                  },
+                  "scheme": {
+                    "default": "Bearer",
+                    "description": "Prefix placed before the value (e.g. 'Bearer'). Empty string sends the raw value.",
+                    "type": "string"
+                  }
+                }
+              }
             }
           }
         }