@edgehero/pi-dispatch 4.1.0 → 4.2.0

package/.env.example

@@ -433,7 +433,8 @@ GITHUB_APP_PRIVATE_KEY=
 # Optional. Set these only to service GitLab projects; leaving GITLAB_TOKEN unset means no /gitlab
 # endpoint exists at all, rather than one that answers 401. See docs/gitlab.md.
 #
-# A PROJECT access token with the `api` scope and the Developer role or above. `api` is the narrowest
+# A PROJECT access token with the `api` scope and the Developer role, not Maintainer (docs/gitlab.md:
+# a Maintainer token lets the job unprotect a branch or change who may merge). `api` is the narrowest
 # scope that can post a note -- GitLab offers no contents-vs-issues split -- so scope it to one project
 # and rotate it (CONST-TOKEN-SCOPED-PER-JOB). A GROUP token reaches every project in the group.
 GITLAB_TOKEN=

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "type": "module",
   "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [
@@ -74,6 +74,7 @@
 		"./backend-conformance": "./src/backend-conformance.mjs",
 		"./live-probes": "./src/live-probes.mjs",
 		"./triggers": "./src/triggers.mjs",
+    "./mcp-config": "./src/mcp-config.mjs",
     "./triggers-file": "./src/triggers-file.mjs",
     "./packages": "./src/packages.mjs",
     "./pause-windows": "./src/pause-windows.mjs",

package/src/doctor.mjs

@@ -66,12 +66,14 @@ import { isTransientOverlayRead, overlayProviderProblem } from "./model-catalog.
 import { EMPTY_USD_FINGERPRINT, usdFingerprint } from "./dollar-fingerprint.mjs";
 import { splitModelEntry } from "./model-ref.mjs";
 import { ignoredOutputCapModels, outputCapView, outputUnboundable } from "./output-cap.mjs";
-import { KEYLESS_API_KEY, KEYLESS_HOW, MODEL_ENDPOINTS_FILE_NAME, MODEL_ENDPOINTS_INCLUDE_NAME, MODEL_ENDPOINT_ID_RE, OVERLAY_LINK_FIX, OVERLAY_NOT_A_FILE_FIX, RENAMED_PROVIDERS, baseUrlTarget, keylessVerdict, loadModelEndpoints, providerRenameHint, readOverlayModels, renderEndpointsInclude, unreportedUsageModels } from "./model-endpoints.mjs";
+import { KEYLESS_API_KEY, KEYLESS_HOW, MODEL_ENDPOINTS_FILE_NAME, MODEL_ENDPOINTS_INCLUDE_NAME, MODEL_ENDPOINT_ID_RE, OVERLAY_LINK_FIX, OVERLAY_NOT_A_FILE_FIX, RENAMED_PROVIDERS, baseUrlTarget, endpointsAt, keylessVerdict, loadModelEndpoints, providerRenameHint, readOverlayModels, renderEndpointsInclude, unreportedUsageModels } from "./model-endpoints.mjs";
 import { declaredEndpointsIn, endpointsDeclaredIn, reloadCommand, rulesFileIncludes, rulesPredateEndpointsLine } from "./egress-cli.mjs";
 import { loadPauseWindows, parseScopeString } from "./pause-windows.mjs";
 import { WAIT_AFTER_MAX_DEFAULT_MS, afterInstantMs, parseWaitProfiles } from "./wait-for.mjs";
 import { isForgeKind } from "./forges.mjs";
 import { findLiteralSecret, ADMIN_RE } from "./import-pi.mjs";
+import { mcpServerWhere, readOverlayMcp } from "./mcp-config.mjs";
+import { allowlistEntryFor, egressRefusalFor, packageRunnerHosts, parseAllowlist } from "./egress-allowlist.mjs";
 import { agentDirFrom, readHostPi } from "./host-pi.mjs";
 import { PACKAGES_SUBDIR, readStagedSkills, readStageManifest } from "./packages.mjs";
 import { copySkillTree } from "./copy-tree.mjs";
@@ -2728,6 +2730,23 @@ export async function collectChecks(shellVars, seams) {
 					},
 				},
 			});
+			// The overlay's MCP servers (REQ-MCP-OPERATOR-SERVERS), through the one parser (mcp-config.mjs).
+			let mcpAllowlist = [];
+			try {
+				mcpAllowlist = parseAllowlist(keylessIo.readFileSync(join(seams.cwd, "egress-allowlist.conf"), "utf8"));
+			} catch {
+				// No allowlist in this folder: every server outside a declared endpoint reads as unreachable, which it is.
+			}
+			checks.push(
+				...overlayMcpChecks({
+					overlay,
+					env,
+					fileExists,
+					read: () => readOverlayMcp(overlay, { readFileSync: seams.readOverlayFile ?? ((p, enc) => readFileSync(p, enc)), ...(seams.lstatOverlayFile ? { lstatSync: seams.lstatOverlayFile } : {}) }),
+					allowlist: mcpAllowlist,
+					endpoints: () => (seams.declaredEndpoints ?? ((a) => declaredEndpointsIn({ ...a, fs: keylessIo })))({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform, valkeyUrl: env.VALKEY_URL ?? DEFAULT_VALKEY_URL }),
+				}),
+			);
 			const modelsPath = join(overlay, "models.json");
 			// Through the one reader (`readOverlayModels`, PR #520): an exists test answered false for a file under an
 			// unreadable directory, so this line passed in silence on a file nobody had read. Absent is a pass (nothing to
@@ -5904,6 +5923,79 @@ export function forgeUrlEgressChecks(env, forges = []) {
 	return checks;
 }
 
+/**
+ * The overlay's MCP servers (REQ-MCP-OPERATOR-SERVERS): whether `mcp.json` reads, each server a job may be offered,
+ * each one refused and why, no `mcp-auth.json` beside it, and, with the egress policy on, whether each streamable HTTP
+ * server is one the proxy lets a job reach. A refused server is one no job can use, so each is ✗; an unreachable one
+ * is ⚠, since the policy may be about to change.
+ * `read` throws the reader's errors; `endpoints` is called only when a server needs it.
+ */
+export function overlayMcpChecks({ overlay, env, fileExists, read, allowlist = [], endpoints = () => [] }) {
+	const checks = [];
+	const authPath = join(overlay, "mcp-auth.json");
+	if (fileExists(authPath)) {
+		checks.push({
+			ok: false,
+			label: "Overlay holds mcp-auth.json, pi's MCP sign-ins, which no job may hold",
+			fix: "delete mcp-auth.json from the overlay; a job's MCP server takes its credential as a ${NAME} reference from run.secrets: docs/mcp.md",
+			fixAction: {
+				tier: "prompt",
+				describe: `rm ${authPath}`,
+				run: async ({ rm }) => {
+					rm(authPath);
+					return { ok: true };
+				},
+			},
+		});
+	}
+	let parsed;
+	try {
+		parsed = read();
+	} catch (error) {
+		const why = error?.mcpConfig ? error.message : `cannot be read (${error?.code ?? "unreadable"})`;
+		checks.push({ ok: false, label: `Overlay mcp.json: ${why}`, fix: "re-run `pi-dispatch import-pi`, or fix the file: docs/mcp.md. Until it reads, no job can use an MCP server" });
+		return checks;
+	}
+	if (parsed === null) return checks;
+	const names = Object.keys(parsed.servers);
+	checks.push({ ok: true, label: names.length === 0 ? "Overlay mcp.json offers no MCP server" : `Overlay mcp.json offers ${names.length} MCP server${names.length === 1 ? "" : "s"} to triggers that name them (${names.join(", ")})` });
+	for (const { name, problem } of parsed.refused) {
+		checks.push({ ok: false, label: `Overlay mcp.json: server ${quotedShown(name)} is refused: ${problem}`, fix: "fix the entry and re-run `pi-dispatch import-pi`: docs/mcp.md. Until then no job can use it" });
+	}
+	let armed = false;
+	try {
+		armed = egressArmed(env) === true;
+	} catch {
+		// A malformed PI_EGRESS: the .env check reports it.
+	}
+	let declared = null;
+	for (const name of names) {
+		const server = parsed.servers[name];
+		if (server.packageRunner) {
+			const missing = packageRunnerHosts(server.command).filter((host) => allowlistEntryFor(allowlist, host) === null);
+			const listed = missing.length === 0;
+			const registry = missing.join(" and ");
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `MCP server ${name} runs ${mcpServerWhere(server)}, which fetches the server from a package registry at the start of every job that uses it`,
+				fix: armed && !listed ? `install the server in the job image instead, or allowlist ${registry} in egress-allowlist.conf: docs/mcp.md` : "install the server in the job image instead, so every job runs the version you chose: docs/mcp.md",
+			});
+		}
+		if (!armed || server.transport !== "http" || server.enabled === false) continue;
+		declared ??= endpoints();
+		const refusal = egressRefusalFor(server.url, { allowlist, endpoints: declared });
+		if (refusal === null) continue;
+		checks.push({
+			ok: false,
+			warn: true,
+			label: `MCP server ${name} (${mcpServerWhere(server)}) is not reachable with the egress policy on: ${refusal}`,
+			fix: "use an https:// url and allowlist its host for 443, or declare its host and port in model-endpoints.json: docs/egress.md. Until then no job can reach it",
+		});
+	}
+	return checks;
+}
+
 /** The canary's three probes. ONE list: the loop names its containers from it and the sweep matches on it. */
 export const CANARY_PROBE_SLUGS = Object.freeze(["provider", "unlisted", "plainhttp"]);
 
@@ -6153,6 +6245,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 	const { declaredEndpoints = ({ env: e, cwd, platform }) => declaredEndpointsIn({ env: e, cwd, fs: { readFileSync, existsSync }, platform }), hostAddresses = () => lanIPv4Addresses(networkInterfaces()) } = seams;
 	const declared = declaredEndpoints({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform });
 	const endpoints = declared.length > 0 && !(!custom && inFolder && !needs.rulesInclude) ? declared : [];
+	const mcpOnly = endpoints.length > 0 ? mcpOnlyEndpoints({ endpoints, ...overlayEndpointUsers(env, seams) }) : new Map();
 	if (endpoints.length > 0) {
 		const runtime = routeRuntimeFromFacts(seams.readFactsOnce ? await seams.readFactsOnce() : null, seams.platform ?? process.platform);
 		const addresses = hostAddresses();
@@ -6259,7 +6352,7 @@ async function egressChecks(env, seams, { dockerCode, imageCode, jobImage, endpo
 	// script. docker's probes keep `runCmdCapture` (its 30 s bound, stderr merged, SIGTERM at the bound) rather than the
 	// bounded step runner, so docker's spawns, and what a probe that never launched leaves for the teardown, are exactly
 	// what they were: pinned in doctor.test.mjs against the output and argv captured before the move.
-	const canary = await runEgressCanary({ run: liveRunVia(spawn), probeRun: (args) => runCmdCapture(spawn, "docker", args), proxy, image: jobImage, pid, gate, endpoints });
+	const canary = await runEgressCanary({ run: liveRunVia(spawn), probeRun: (args) => runCmdCapture(spawn, "docker", args), proxy, image: jobImage, pid, gate, endpoints, mcpOnly });
 	// Through a stale proxy the canary reads THAT proxy's policy (exec round 3): a failure is the proxy's to fix, never
 	// this deployment's allowlist, which it may not even mount.
 	checks.push(...(staleRunning ? canary.checks.map((c) => (c.ok ? c : { ...c, fix: `the canary ran through ${proxy}, which is not this deployment's proxy (above), so this says nothing about egress-allowlist.conf: ${replaceFix}, then re-run doctor` })) : canary.checks));
@@ -6353,8 +6446,10 @@ const CANARY_NO_WORKSPACE = "/nonexistent/pi-dispatch-egress-canary-mounts-nothi
  *
  * `endpoints` (issue #503) are the declared model endpoints to prove on the same network after the three
  * (`runEndpointProbes`), `[]` by default, so the conformance script and a deployment with none run exactly the three.
+ * `mcpOnly` maps the ids of those only an overlay MCP server uses (`mcpOnlyEndpoints`), whose `models` probe proves
+ * the route and is not judged as a model server's answer.
  */
-export async function runEgressCanary({ run, bin = "docker", proxy, image, pid = process.pid, user = null, probeRun = null, endpoints = [], size = DEFAULT_JOB_SIZE, hostCpus = null, gate = makeDetachGate((args, opts) => run(args, { timeoutMs: opts?.timeoutMs ?? CANARY_STEP_TIMEOUT_MS }), { bin }) }) {
+export async function runEgressCanary({ run, bin = "docker", proxy, image, pid = process.pid, user = null, probeRun = null, endpoints = [], mcpOnly = new Map(), size = DEFAULT_JOB_SIZE, hostCpus = null, gate = makeDetachGate((args, opts) => run(args, { timeoutMs: opts?.timeoutMs ?? CANARY_STEP_TIMEOUT_MS }), { bin }) }) {
 	const venue = canaryVenueFor(bin);
 	const probe = probeRun ?? ((args) => run(args, { timeoutMs: bin === "podman" ? PODMAN_FIRST_START_TIMEOUT_MS : RUN_TIMEOUTS.cmd }));
 	const checks = [];
@@ -6509,7 +6604,7 @@ export async function runEgressCanary({ run, bin = "docker", proxy, image, pid =
 			if (staleRunner) {
 				checks.push({ ok: false, warn: true, label: `${venue.prefix}Model endpoints: not probed, because the job image has no runner module (above), and their probes take the runner's route`, fix: "use a job image built after issue #427, then re-run doctor" });
 			} else {
-				checks.push(...(await runEndpointProbes({ probe, bin, pid, network: net, proxy, image, user, endpoints, venue, unfinished, size, hostCpus })));
+				checks.push(...(await runEndpointProbes({ probe, bin, pid, network: net, proxy, image, user, endpoints, mcpOnly, venue, unfinished, size, hostCpus })));
 			}
 		}
 	} finally {
@@ -6613,6 +6708,66 @@ function endpointsById(endpoints) {
 	return [...endpoints].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
 }
 
+/**
+ * The declared endpoints that an overlay MCP server dials (an enabled streamable HTTP server's `url` in `mcp.json`, the
+ * servers doctor's own MCP check and the pickup judge) and no overlay model does (a provider's or a model's `baseUrl` in `models.json`), each matched by `endpointsAt`, as the
+ * pickup's egress check matches an MCP server to an endpoint. docs/egress.md has an operator declare an MCP server off
+ * port 443 there, and such a server does not serve `/v1/models`: it answers 404 or 405, and the `models` probe used to
+ * warn on every run that the port was not the model server's. Its tunnel is still opened and its route proved; only its
+ * answer is not judged as a model server's. An endpoint both use is probed as a model server, since a model needs that.
+ * A models.json that could not be read is not evidence that no model uses an endpoint, so nothing is MCP-only then.
+ * Returns a Map of endpoint id to `{ tls }`, `tls` when a server's url on it is `https:`: the probe's plain request then
+ * meets a TLS server, which closes the socket rather than answer (`endpointProbeCheck`).
+ */
+export function mcpOnlyEndpoints({ endpoints, mcp = null, models = null, modelsUnread = false }) {
+	if (modelsUnread || !Array.isArray(endpoints) || endpoints.length === 0) return new Map();
+	const idsAt = (urls) => new Set(urls.flatMap((url) => endpointsAt(url, endpoints).map((e) => e.id)));
+	const mcpUrls = Object.values(mcp?.servers ?? {})
+		.filter((server) => server.transport === "http" && server.enabled !== false)
+		.map((server) => server.url);
+	const modelUrls = [];
+	const providers = models?.providers;
+	for (const entry of providers !== null && typeof providers === "object" ? Object.values(providers) : []) {
+		if (entry === null || typeof entry !== "object") continue;
+		modelUrls.push(entry.baseUrl);
+		for (const model of Array.isArray(entry.models) ? entry.models : []) modelUrls.push(model?.baseUrl);
+	}
+	const byModels = idsAt(modelUrls);
+	const only = new Map();
+	for (const url of mcpUrls) {
+		for (const { id } of endpointsAt(url, endpoints)) {
+			if (byModels.has(id)) continue;
+			only.set(id, { tls: only.get(id)?.tls === true || new URL(url).protocol === "https:" });
+		}
+	}
+	return only;
+}
+
+/**
+ * The overlay's mcp.json and models.json for `mcpOnlyEndpoints`, through the readers the overlay section uses and its
+ * seams. An mcp.json that cannot be read offers no server here (its own line says why); a models.json that cannot be read
+ * is `modelsUnread`, which keeps every endpoint probed as a model server.
+ */
+function overlayEndpointUsers(env, seams) {
+	const overlay = env.PI_GLOBAL_PI_DIR;
+	if (typeof overlay !== "string" || !isAbsolute(overlay)) return {};
+	const io = { readFileSync: seams.readOverlayFile ?? ((p, enc) => readFileSync(p, enc)), ...(seams.lstatOverlayFile ? { lstatSync: seams.lstatOverlayFile } : {}) };
+	let mcp = null;
+	try {
+		mcp = readOverlayMcp(overlay, io);
+	} catch {
+		// Named by the overlay section's own line.
+	}
+	try {
+		return { mcp, models: readOverlayModels(overlay, io) };
+	} catch {
+		return { mcp, modelsUnread: true };
+	}
+}
+
+/** The `blocked` codes of a socket the far end closed: what an https server does with the probe's plain request. */
+const SOCKET_CLOSED_CODES = Object.freeze(["UND_ERR_SOCKET", "ECONNRESET"]);
+
 /** The exits each probe's script ends a READING with; any other exit is a container that did not run it. */
 const ENDPOINT_PROBE_READ_EXITS = Object.freeze({ models: [0, 3, 6], nextport: [0, 3, 6], plain: [0, 3] });
 
@@ -6625,8 +6780,8 @@ const ENDPOINT_PROBE_READ_EXITS = Object.freeze({ models: [0, 3, 6], nextport: [
  *   - `plain`: a 403 carrying squid's `X-Squid-Error: ERR_ACCESS_DENIED`. A bare 403 may be the server's own answer to a
  *     request the proxy forwarded.
  */
-function endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next }) {
-	const head = `${venue.prefix}Model endpoint ${endpoint.id}`;
+function endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next, mcpOnly = null }) {
+	const head = mcpOnly ? `${venue.prefix}MCP server endpoint ${endpoint.id}` : `${venue.prefix}Model endpoint ${endpoint.id}`;
 	const at = endpointAddress(endpoint.host, endpoint.port);
 	const reading = endpointProbeReading(answer);
 	const tag = { id: endpoint.id, probe: slug, kind: reading?.kind ?? null, status: reading?.status ?? null };
@@ -6641,6 +6796,19 @@ function endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next })
 	}
 	const reload = reloadCommand(bin, proxy);
 	if (slug === "models") {
+		// An endpoint only an overlay MCP server uses: any answer through the tunnel proves the route and the rule, and
+		// what it says to /v1/models is not a model server's answer (`mcpOnlyEndpoints`). Not reaching it still fails below.
+		if (mcpOnly && reading.kind === "reached") {
+			return { ok: true, warn: true, label: `${head}: the route through the proxy works (the tunnel to ${at} opened and the server answered ${reading.status}); no overlay model uses it, so it is not probed as a model server`, endpointProbe: tag };
+		}
+		// An https MCP server meets the probe's plain request as TLS servers do: it closes the socket (measured: undici reads
+		// UND_ERR_SOCKET, "other side closed"; a reset is the same fact). Only a CONNECT the proxy let through reaches the
+		// server to be closed by it, since a refused tunnel reads as `tunnel`, so the route is proved. Not a timeout, and
+		// not a code that says the proxy itself was not reached (ECONNREFUSED to it, a name it could not resolve).
+		if (mcpOnly?.tls && reading.kind === "blocked" && SOCKET_CLOSED_CODES.includes(reading.detail)) {
+			return { ok: true, warn: true, label: `${head}: the route through the proxy works (the tunnel to ${at} opened and the server closed a plain request, as a TLS server does: ${reading.detail}); no overlay model uses it, so it is not probed as a model server`, endpointProbe: tag };
+		}
+		const server = mcpOnly ? "MCP server" : "model server";
 		if (reading.kind === "reached" && reading.status === 200) return { ok: true, warn: true, label: `${head} answers through the proxy (GET http://${at}/v1/models through a CONNECT tunnel: 200)`, endpointProbe: tag };
 		// The SERVER refused the request for want of a key (vLLM --api-key, a gateway in front): the route and the rule are
 		// proved, since only an open tunnel carries the server's own answer. Said apart from a fault, still warn-tier.
@@ -6673,10 +6841,12 @@ function endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next })
 				: reading.kind === "reached"
 					? "check that this port is the model server's and that it serves the OpenAI-compatible API under /v1 (Ollama, llama-server, vLLM and LM Studio do)"
 					: timedOut
-						? "the server is there but stuck or busy (a model still loading, every slot taken): check its own log, then re-run doctor"
+						? mcpOnly
+							? "the server is there but stuck or busy: check its own log, then re-run doctor"
+							: "the server is there but stuck or busy (a model still loading, every slot taken): check its own log, then re-run doctor"
 						: bin === "podman"
-							? `start the model server, bound to this host's LAN address or 0.0.0.0 (never 127.0.0.1 alone), and declare a server on this host as host.containers.internal (docs/egress.md, "Local model servers"). A job meets this as "Connection error"`
-							: `start the model server, and check it listens where the proxy reaches it (docs/egress.md, "Local model servers"; on Docker Engine that is 172.17.0.1 or 0.0.0.0, never 127.0.0.1 alone). A job meets this as "Connection error"`;
+							? `start the ${server}, bound to this host's LAN address or 0.0.0.0 (never 127.0.0.1 alone), and declare a server on this host as host.containers.internal (docs/egress.md, "Local model servers"). A job meets this as "Connection error"`
+							: `start the ${server}, and check it listens where the proxy reaches it (docs/egress.md, "Local model servers"; on Docker Engine that is 172.17.0.1 or 0.0.0.0, never 127.0.0.1 alone). A job meets this as "Connection error"`;
 		return { ok: false, warn: true, label: `${head} does NOT answer: ${why}`, fix, endpointProbe: tag };
 	}
 	const wider = `the proxy's rules are wider than model-endpoints.conf renders: compare the include inside it (\`${bin} exec ${proxy} cat ${ENDPOINTS_INCLUDE_IN_PROXY}\`) with \`pi-dispatch egress render\`'s, check egress-allowlist.conf does not list ${endpoint.host}, then \`${reload}\``;
@@ -6725,7 +6895,7 @@ export function undeclaredPortNear(endpoint, endpoints) {
  * variable as well on docker: the runner's dispatcher sends an `http://` origin to HTTP_PROXY, which docker's canary
  * argv does not otherwise carry (podman's is a job's environment and has it).
  */
-async function runEndpointProbes({ probe, bin, pid, network, proxy, image, user, endpoints, venue, unfinished, size = DEFAULT_JOB_SIZE, hostCpus = null }) {
+async function runEndpointProbes({ probe, bin, pid, network, proxy, image, user, endpoints, mcpOnly = new Map(), venue, unfinished, size = DEFAULT_JOB_SIZE, hostCpus = null }) {
 	const checks = [];
 	for (const endpoint of endpointsById(endpoints)) {
 		const next = undeclaredPortNear(endpoint, endpoints);
@@ -6740,7 +6910,7 @@ async function runEndpointProbes({ probe, bin, pid, network, proxy, image, user,
 			const name = egressEndpointProbe(slug, endpoint.id, pid);
 			const answer = await probe(egressCanaryProbeArgs({ bin, slug, name, pid, network, proxy, image, url, user, script, httpProxy: true, size, hostCpus }));
 			if (answer?.code === null && answer.ended !== "error") unfinished.push(name);
-			checks.push(endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next }));
+			checks.push(endpointProbeCheck({ slug, endpoint, answer, venue, bin, proxy, next, mcpOnly: mcpOnly.get(endpoint.id) ?? null }));
 		}
 	}
 	return checks;
@@ -8706,6 +8876,7 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 	// Issue #503: the declared model endpoints `--live` probes on this venue, `[]` for none; and whether the rules the
 	// proxy runs include their file (only the shipped proxy's account copy is read; another proxy must include it).
 	let endpoints = [];
+	let mcpOnly = new Map();
 	let endpointRulesInclude = true;
 	if (armed !== false) {
 		// `.State.Status` (issue #453): only `running` carries traffic; Podman reports paused and between-restarts states
@@ -8772,6 +8943,7 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 		const declaredList = declaredEndpoints({ env, cwd: seams.cwd, platform: seams.platform ?? process.platform });
 		if (declaredList.length > 0 && endpointRulesInclude) {
 			endpoints = declaredList;
+			mcpOnly = mcpOnlyEndpoints({ endpoints, ...overlayEndpointUsers(env, seams) });
 			// The helper as Podman 5 names it in `podman info` (`rootlessNetworkCmd`), else as this account's running rootless
 			// network shows it (`observeRootlessNetns`, the record or the 4.x argv the worker's widening check reads), else
 			// not known, which the route row says as such.
@@ -8795,7 +8967,7 @@ export async function podmanChecks(env, seams, { jobImage, jobImageNote = "" })
 		if (keeperNetwork) checks.push(keeperNetwork);
 	}
 
-	forLive = { run: true, user, relabel, info, imagePresent, egress: { armed, proxy, proxyRunning, keeperBlocked, endpoints } };
+	forLive = { run: true, user, relabel, info, imagePresent, egress: { armed, proxy, proxyRunning, keeperBlocked, endpoints, mcpOnly } };
 	return { checks, observed, relabel, imagesReadable, imageDigest, forLive };
 }
 
@@ -9320,7 +9492,7 @@ async function podmanEgressCanary({ podman, readInfo, run, image, pid, isAlive,
 	const endpoints = podman.egress.endpoints ?? [];
 	const more = endpoints.length > 0 ? `; then three per declared model endpoint (${endpointsById(endpoints).map((e) => e.id).join(", ")}), named ${EGRESS_ENDPOINT_PROBE_PREFIX}<probe>-<id>-${pid}, removed the same way` : "";
 	announce(`starting ${probes.slice(0, -1).join(", ")} and ${probes.at(-1)} from ${image} (as the job user ${podman.user}) on the --internal network ${egressCanaryNetwork(pid)}, with ${podman.egress.proxy} attached, to read the egress allowlist back; all three are removed when the canary ends${more}`);
-	const canary = await runEgressCanary({ run, bin: "podman", proxy: podman.egress.proxy, image, pid, user: podman.user, gate, endpoints, size, hostCpus: again.info?.hostCpus ?? null });
+	const canary = await runEgressCanary({ run, bin: "podman", proxy: podman.egress.proxy, image, pid, user: podman.user, gate, endpoints, mcpOnly: podman.egress.mcpOnly ?? new Map(), size, hostCpus: again.info?.hostCpus ?? null });
 	return { checks: [...checks, ...canary.checks], results: canary.results };
 }
 

package/src/egress-allowlist.mjs

@@ -0,0 +1,81 @@
+/**
+ * The egress allowlist as the proxy reads it, and whether a URL a job dials gets through (docs/egress.md). Squid
+ * matches `egress-allowlist.conf` as a `dstdomain` file (deploy/egress-proxy.conf, `acl allowed dstdomain -n`): each
+ * line, trimmed and with a `#` comment removed, is ONE entry, and an entry with a leading dot admits that domain and
+ * every name under it. A line with two words is one entry that matches nothing (measured on the pinned squid: both
+ * names refused), so it admits nothing here either. A job's runner sends every request as a CONNECT
+ * (image/runner/src/env-proxy.mjs, `proxyTunnel: true`), and the proxy allows a CONNECT to an allowlisted name on port
+ * 443 only, never to a host that resolves to this machine (`to_host_local`), and to a declared model endpoint on
+ * exactly its host and port (`model-endpoints.conf`).
+ *
+ * The proxy stays the enforcement. This is the same reading done before anything is spent, so a job whose server the
+ * policy cannot serve is refused with a reason instead of failing at its first call. It is a necessary condition, not
+ * a sufficient one: a NAME that resolves to this machine is refused by the proxy and not here, since this reads no DNS.
+ */
+import { isIP } from "node:net";
+import { basename } from "node:path";
+import { isProxyLocalHost } from "./backends.mjs";
+import { baseUrlTarget, endpointsAt } from "./model-endpoints.mjs";
+
+/** The entries of an allowlist's text, lowercased, in order: one per line, a line with inner whitespace skipped. */
+export function parseAllowlist(text) {
+	const entries = [];
+	for (const raw of String(text ?? "").split(/\r?\n/)) {
+		// A comment starts at a `#` that opens the line or follows whitespace; one inside a word is part of the word,
+		// which then matches no host.
+		const line = raw.replace(/(^|\s)#.*$/, "").trim();
+		if (line === "" || /\s/.test(line)) continue;
+		entries.push(line.toLowerCase());
+	}
+	return entries;
+}
+
+/** The first entry that admits `host`, or null: the name itself, or a leading-dot entry for it or a name above it. */
+export function allowlistEntryFor(entries, host) {
+	const name = String(host).toLowerCase();
+	for (const entry of entries) {
+		if (entry.startsWith(".") ? name === entry.slice(1) || name.endsWith(entry) : name === entry) return entry;
+	}
+	return null;
+}
+
+/** Whether `host` (as `baseUrlTarget` gives it) is an address squid's `to_host_local` refuses, or `localhost`. */
+function hostIsLocal(host) {
+	const bare = host.startsWith("[") ? host.slice(1, -1) : host;
+	const kind = isIP(bare) === 4 ? "ipv4" : isIP(bare) === 6 ? "ipv6" : "name";
+	if (isProxyLocalHost(kind, bare)) return true;
+	if (kind === "ipv4") return bare.startsWith("169.254.");
+	if (kind === "ipv6") return /^fe[89ab][0-9a-f]:/i.test(bare);
+	return false;
+}
+
+/**
+ * Why a job's CONNECT to `url` would be refused by the proxy, or null when it gets through: a declared endpoint's
+ * exact host and port, or an allowlisted name on port 443, over https, that is not this machine. Both schemes go as
+ * a CONNECT, so the proxy itself does not tell them apart.
+ */
+export function egressRefusalFor(url, { allowlist = [], endpoints = [] } = {}) {
+	const target = baseUrlTarget(url);
+	if (target === null) return "it is not an http or https URL";
+	if (endpointsAt(url, endpoints).length > 0) return null;
+	const entry = allowlistEntryFor(allowlist, target.host);
+	if (entry !== null && hostIsLocal(target.host)) return `${target.host} is the proxy's own machine, which it never opens; a server on this machine is declared in model-endpoints.json under host.docker.internal or host.containers.internal`;
+	// The proxy tunnels to 443 whatever speaks inside, so an `http://` url on 443 is plain HTTP to what is almost always
+	// a TLS port, carrying the server's headers in clear inside the tunnel: refused, with the fix.
+	if (entry !== null && target.port === 443 && new URL(url).protocol !== "https:") return `the egress proxy opens ${target.host} on port 443 for TLS, and this url is http://; use https://`;
+	if (entry !== null && target.port === 443) return null;
+	if (entry !== null) return `the egress proxy opens ${target.host} on port 443 only, and this is port ${target.port}; declare ${target.host}:${target.port} in model-endpoints.json to open exactly that port`;
+	return `${target.host} is not in egress-allowlist.conf${target.port === 443 ? "" : ", and port " + target.port + " opens only as a declared endpoint in model-endpoints.json"}`;
+}
+
+/**
+ * Every host a package runner fetches from at start, by name, since the proxy matches names: uv and pipx take the
+ * index from pypi.org and the files from files.pythonhosted.org, yarn's default registry is its own name, and the npm
+ * family reads registry.npmjs.org.
+ */
+export function packageRunnerHosts(command) {
+	const runner = basename(String(command));
+	if (["uv", "uvx", "pipx"].includes(runner)) return ["pypi.org", "files.pythonhosted.org"];
+	if (runner === "yarn") return ["registry.yarnpkg.com"];
+	return ["registry.npmjs.org"];
+}

package/src/env-allowlist.mjs

@@ -367,7 +367,7 @@ function resolveEnvName(provider) {
  * `allowGlobalExtensions` defaults to TRUE here, matching loadConfig's default (REQ-GLOBAL-PI-OVERLAY): a
  * caller that says nothing gets the operator's staged setup, and only an explicit `false` withholds it.
  */
-export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
+export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCostMicros = null, jobId, githubToken, forgeKind, forgeHosts = {}, hostEnv, allowGlobalExtensions = true, packagePaths = [], forwardEnv = [], secrets = {}, sessionFile = null, flow = null, command = null, excludeTools = [], mcpServers = [], allowedModels = null, authFromPi = false, egress = false, egressProxy, agentDir, home = null, readFile = readFileSync, modelEndpoints = null, exitAuth = false }) {
 	// The provider credential(s), by pi's expected variable name(s) -- from the worker env, or (when
 	// PI_AUTH_FROM_PI is set and the env has none) host-side from pi's auth.json. Throws (config) if
 	// neither source yields one, which the processor turns into a policy refusal that refunds any reserve
@@ -429,6 +429,10 @@ export function buildContainerEnv({ provider, model, maxTurns, maxTokens, maxCos
 		// second-validator rule directly above). Absent means the full pinned default set, never an empty
 		// string, for PI_PACKAGES' reason.
 		PI_EXCLUDE_TOOLS: excludeTools.length > 0 ? excludeTools.join(",") : undefined,
+		// The trigger's run.mcp (REQ-MCP-OPERATOR-SERVERS): the overlay servers the job's session connects, so the
+		// runner can hold `/job/mcp.json` to the names the worker meant. Comma-safe for excludeTools' reason (the loader
+		// admits only lowercase letters, digits and `-`). Absent means none, never an empty string.
+		PI_MCP_SERVERS: mcpServers.length > 0 ? mcpServers.join(",") : undefined,
 		// The job's EFFECTIVE allowed-model list (issue #502): its trigger's `run.models`, else the deployment's
 		// PI_ALLOWED_MODELS. Comma-joined `provider/model` entries, which the runner splits at each entry's first `/`
 		// (image/runner/src/config.mjs). Comma is safe because both list parsers refuse an entry carrying one. NULL is

package/src/image-preflight.mjs

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
 import { imageRefProblem } from "./image-ref.mjs";
+import { FORGE_MCP_SERVER_NAME } from "./mcp-config.mjs";
 
 /**
  * Which image a job runs in, and whether it is on this host.
@@ -44,7 +45,9 @@ export function resolveJobImage(job, defaultImage) {
  *   { forgeUnsupported }  -- present, but declares it cannot serve this job's forge => POLICY, refuse
  *   { <gate.result>, declared } -- present, but does not declare a capability this job needs, one key per
  *                            CAPABILITY_GATES row (replicaUnsupported, commandUnsupported,
- *                            excludeToolsUnsupported, modelPolicyUnsupported, costCapUnsupported) => POLICY
+ *                            excludeToolsUnsupported, modelPolicyUnsupported, costCapUnsupported, mcpUnsupported,
+ *                            forgeMcpUnsupported)
+ *                            => POLICY
  *
  * A non-zero `docker image inspect` is AMBIGUOUS -- an absent image and an unreachable daemon both exit 1 --
  * so the failure path disambiguates POSITIVELY with `docker info` rather than by matching docker's stderr.
@@ -191,6 +194,27 @@ export const CAPABILITY_GATES = Object.freeze([
 		event: "refused_image_cost_cap_unsupported",
 		comment: (image, declared) => `Refused: the job image "${image}" does not declare cost-cap support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would ignore the per-job dollar cap and run this job with no cap at all. Rebuild the image from a version that has this feature. Not run.`,
 	}),
+	// REQ-MCP-OPERATOR-SERVERS: a runner that predates run.mcp reads no /job/mcp.json, so the job would run without
+	// the servers its flow was written against and record a clean exit while the file reads as though it named them.
+	Object.freeze({
+		token: "mcp",
+		needed: (job) => Array.isArray(job?.mcp) && job.mcp.length > 0,
+		result: "mcpUnsupported",
+		reason: "job-image-mcp-unsupported",
+		event: "refused_image_mcp_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare MCP support (\`dev.pi-dispatch.capabilities\` ${declared}), so its runner would not connect the servers \`run.mcp\` names. Rebuild the image from a version that has this feature. Not run.`,
+	}),
+	// DES-FORGE-MCP: `forge` in run.mcp starts a server the IMAGE carries (github-mcp-server, mcp-gitlab), not one the
+	// overlay names. An image with `mcp` and without them would pass every gate, reserve the budget, and refuse at the
+	// container's start as mcp-command-missing; this row says so before anything is spent.
+	Object.freeze({
+		token: "forgeMcp",
+		needed: (job) => Array.isArray(job?.mcp) && job.mcp.includes(FORGE_MCP_SERVER_NAME),
+		result: "forgeMcpUnsupported",
+		reason: "job-image-forge-mcp-unsupported",
+		event: "refused_image_forge_mcp_unsupported",
+		comment: (image, declared) => `Refused: the job image "${image}" does not declare the forge's own MCP server (\`dev.pi-dispatch.capabilities\` ${declared}), so it does not carry the server \`run.mcp\` names as \`forge\`. Rebuild the image from a version that has this feature. Not run.`,
+	}),
 ]);
 
 /**