ruvnet/ruflo · error

[mcp] failed to parse MCP_SERVERS env

Error message

[mcp] failed to parse MCP_SERVERS env

What it means

Log warning from parseServers: the MCP_SERVERS environment variable could not be parsed into valid server entries (invalid JSON structure, missing/blank name or url fields), so malformed entries are skipped or the whole set ignored when building the MCP server registry.

Source

Thrown at ruflo/src/ruvocal/src/lib/server/mcp/registry.ts:37

				const name = (entry as Record<string, unknown>).name;
				const url = (entry as Record<string, unknown>).url;
				if (typeof name !== "string" || !name.trim()) return undefined;
				if (typeof url !== "string" || !url.trim()) return undefined;

				const headersRaw = (entry as Record<string, unknown>).headers;
				let headers: Record<string, string> | undefined;
				if (headersRaw && typeof headersRaw === "object" && !Array.isArray(headersRaw)) {
					const headerEntries = Object.entries(headersRaw as Record<string, unknown>).filter(
						(entry): entry is [string, string] => typeof entry[1] === "string"
					);
					headers = Object.fromEntries(headerEntries);
				}

				return headers ? { name, url, headers } : { name, url };
			})
			.filter((server): server is McpServerConfig => Boolean(server));
	} catch (error) {
		logger.warn({ err: error }, "[mcp] failed to parse MCP_SERVERS env");
		return [];
	}
}

function setServers(raw: string) {
	cachedServers = parseServers(raw);
	cachedRaw = raw;
	resetMcpToolsCache();
	logger.debug({ count: cachedServers.length }, "[mcp] loaded server configuration");
	console.log(
		`[MCP] Loaded ${cachedServers.length} server(s):`,
		cachedServers.map((s) => s.name).join(", ") || "none"
	);
}

export function loadMcpServersOnStartup(): McpServerConfig[] {
	const raw = config.MCP_SERVERS || "[]";
	setServers(raw);

View on GitHub (pinned to fa13ee4ad6)

Solutions

1. Fix the MCP_SERVERS environment variable to contain valid JSON matching the expected schema.
2. Unset MCP_SERVERS to use the default configuration, then reintroduce entries incrementally to find the malformed one.

When it happens

Trigger: Thrown at ruflo/src/ruvocal/src/lib/server/mcp/registry.ts:37 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

AI-assisted analysis of ruvnet/ruflo@fa13ee4ad6 (2026-08-18). Data as JSON: /api/errors/eed22ce3a2a413ef. Report an issue: GitHub.