Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): bind autostarted server to 127.0.0.1, not localhost (PRD-7259) (#2389)

mike-inkeepbe8195b097e4
diff --git a/.changeset/windows-ipv4-loopback-bind.md b/.changeset/windows-ipv4-loopback-bind.md
new file mode 100644
index 000000000..4072c6c45
--- /dev/null
+++ b/.changeset/windows-ipv4-loopback-bind.md
@@ -0,0 +1,13 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Fix the server being unreachable on Windows when your coding agent auto-starts
+it over MCP. The server used to bind the `localhost` hostname, which Windows
+resolves to IPv6 (`::1`) only, while the tools connecting to it use IPv4
+(`127.0.0.1`) — so `edit` / `exec` calls failed with "Server unreachable: fetch
+failed". The server now binds numeric `127.0.0.1` directly (still loopback-only),
+and the MCP shim and the `ok ui` proxy connect to the same address, so there is
+no longer any IPv4/IPv6 mismatch on any platform. You no longer need the
+`--host 127.0.0.1` / `HOST=127.0.0.1` workaround. macOS and Linux behavior is
+unchanged.
diff --git a/packages/cli/src/commands/start.test.ts b/packages/cli/src/commands/start.test.ts
index 91e93b903..1381ab685 100644
--- a/packages/cli/src/commands/start.test.ts
+++ b/packages/cli/src/commands/start.test.ts
@@ -41,8 +41,8 @@ describe('resolveHost', () => {
expect(resolveHost({}, { HOST: '0.0.0.0' })).toBe('0.0.0.0');
});
- test('falls back to DEFAULT_SERVER_HOST (localhost) when both flag and env are absent', () => {
- expect(resolveHost({}, {})).toBe('localhost');
+ test('falls back to DEFAULT_SERVER_HOST (numeric IPv4 loopback) when both flag and env are absent', () => {
+ expect(resolveHost({}, {})).toBe('127.0.0.1');
});
test('explicit undefined --host falls through to env (precedence: flag > env > default)', () => {
diff --git a/packages/cli/src/commands/ui.ts b/packages/cli/src/commands/ui.ts
index 4aea32dcf..a7f6cd636 100644
--- a/packages/cli/src/commands/ui.ts
+++ b/packages/cli/src/commands/ui.ts
@@ -1,6 +1,7 @@
import type { Server as HttpServer, ServerResponse } from 'node:http';
import {
ASSET_EXTENSIONS,
+ DEFAULT_SERVER_HOST,
defaultScheduler,
EXECUTABLE_BLOCKLIST_EXTENSIONS,
INLINE_RENDERABLE_EXTENSIONS,
@@ -177,7 +178,7 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServe
return;
}
proxyRequest(req, res, {
- upstreamHost: 'localhost',
+ upstreamHost: DEFAULT_SERVER_HOST,
upstreamPort: lock.port,
});
return;
@@ -237,7 +238,14 @@ export async function startUiServer(opts: StartUiServerOptions): Promise<UiServe
clientSocket.destroy();
return;
}
- proxyUpgrade(req, clientSocket, head, 'localhost', lock.port, upgradeSocketsForShutdown);
+ proxyUpgrade(
+ req,
+ clientSocket,
+ head,
+ DEFAULT_SERVER_HOST,
+ lock.port,
+ upgradeSocketsForShutdown,
+ );
};
const drainUpgradeSockets = (): void => {
for (const sock of upgradeSocketsForShutdown) {
diff --git a/packages/cli/src/mcp/shim.test.ts b/packages/cli/src/mcp/shim.test.ts
index 2f938d8c3..3e16ed918 100644
--- a/packages/cli/src/mcp/shim.test.ts
+++ b/packages/cli/src/mcp/shim.test.ts
@@ -91,7 +91,7 @@ describe('MCP stdio shim server resolution', () => {
}) as never,
});
- expect(url).toBe('http://localhost:4123/mcp');
+ expect(url).toBe('http://127.0.0.1:4123/mcp');
});
test('missing lock spawns ok start and polls until a live port appears', async () => {
@@ -126,7 +126,7 @@ describe('MCP stdio shim server resolution', () => {
pollIntervalMs: 1,
});
- expect(url).toBe('http://localhost:4123/mcp');
+ expect(url).toBe('http://127.0.0.1:4123/mcp');
expect(calls).toHaveLength(1);
expect(calls[0]?.cmd).toBe(process.execPath);
expect(calls[0]?.args.at(-1)).toBe('start');
@@ -146,7 +146,7 @@ describe('MCP stdio shim server resolution', () => {
expect((err as Error).message).toContain('OK_MCP_AUTOSTART=0');
});
- test('valid port override bypasses discovery and formats wildcard host as localhost', async () => {
+ test('valid port override bypasses discovery and targets the default loopback host', async () => {
const url = await resolveMcpHttpUrl({
lockDir,
contentDir: tmp,
@@ -160,7 +160,7 @@ describe('MCP stdio shim server resolution', () => {
}) as never,
});
- expect(url).toBe('http://localhost:6789/mcp');
+ expect(url).toBe('http://127.0.0.1:6789/mcp');
});
test('invalid port override rejects before spawn', async () => {
@@ -261,7 +261,7 @@ describe('MCP stdio shim server resolution', () => {
},
'http://localhost:4123/mcp',
),
- ).toBe('ws://localhost:4123');
+ ).toBe('ws://127.0.0.1:4123');
expect(
resolveMcpKeepaliveWsUrl(
diff --git a/packages/cli/src/mcp/shim.ts b/packages/cli/src/mcp/shim.ts
index a33987c79..51f489473 100644
--- a/packages/cli/src/mcp/shim.ts
+++ b/packages/cli/src/mcp/shim.ts
@@ -4,7 +4,11 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync } from 'node:f
import { join } from 'node:path';
import type { Readable, Writable } from 'node:stream';
import { setTimeout as wait } from 'node:timers/promises';
-import { clientVersionHeaders, SPAWN_ERROR_LOG } from '@inkeep/open-knowledge-core';
+import {
+ clientVersionHeaders,
+ DEFAULT_SERVER_HOST,
+ SPAWN_ERROR_LOG,
+} from '@inkeep/open-knowledge-core';
import { startKeepalive as defaultStartKeepalive } from '@inkeep/open-knowledge-core/keepalive';
import {
AutoStartDisabledError,
@@ -184,11 +188,11 @@ export async function resolveMcpHttpUrl(opts: ResolveMcpHttpUrlOptions): Promise
`invalid --port value '${opts.portOverride}' — HTTP MCP shim requires a positive port`,
);
}
- return mcpUrlForPort('localhost', parsed);
+ return mcpUrlForPort(DEFAULT_SERVER_HOST, parsed);
}
const existingPort = livePortFromLock(readLock(), isAlive);
- if (existingPort !== undefined) return mcpUrlForPort('localhost', existingPort);
+ if (existingPort !== undefined) return mcpUrlForPort(DEFAULT_SERVER_HOST, existingPort);
if (opts.envAutoStart === '0') {
throw new AutoStartDisabledError(
@@ -237,7 +241,7 @@ export async function resolveMcpHttpUrl(opts: ResolveMcpHttpUrlOptions): Promise
}
await sleep(pollIntervalMs);
const port = livePortFromLock(readLock(), isAlive);
- if (port !== undefined) return mcpUrlForPort('localhost', port);
+ if (port !== undefined) return mcpUrlForPort(DEFAULT_SERVER_HOST, port);
}
if (asyncSpawnError) {
@@ -257,7 +261,7 @@ export function resolveMcpKeepaliveWsUrl(
const readLock = opts.readLock ?? (() => readServerLock(opts.lockDir));
const isAlive = opts.isAlive ?? defaultIsProcessAlive;
const port = livePortFromLock(readLock(), isAlive);
- if (port !== undefined) return wsUrlForPort('localhost', port);
+ if (port !== undefined) return wsUrlForPort(DEFAULT_SERVER_HOST, port);
return undefined;
}
diff --git a/packages/core/src/constants/server.ts b/packages/core/src/constants/server.ts
index b544a778b..3fc5ebf31 100644
--- a/packages/core/src/constants/server.ts
+++ b/packages/core/src/constants/server.ts
@@ -1 +1 @@
-export const DEFAULT_SERVER_HOST = 'localhost';
+export const DEFAULT_SERVER_HOST = '127.0.0.1';