vercel/ai · error

The host tool MCP relay is unavailable.

Error message

The host tool MCP relay is unavailable.

What it means

runTurn asserts that the local host tool MCP relay server was started during initialization (hostToolRelay non-null) before executing the turn, because agent tool calls that need host-side execution must be able to reach this relay. If the relay was never created or failed to start silently, this Error is thrown and the turn aborts.

Source

Thrown at packages/harness-acp/src/v1/bridge/index.ts:162

    if (HarnessBridgeCapabilityUnsupportedError.isInstance(error)) throw error;
    throw createACPBridgeError({
      stage: 'session initialization',
      cause: error,
    });
  }
  const activeSession = session;
  if (activeSession == null) {
    throw new Error('ACP session initialization did not produce a session.');
  }
  const activeAgentResponseStreamFailure = agentResponseStreamFailure;
  if (activeAgentResponseStreamFailure == null) {
    throw new Error(
      'ACP session initialization did not start stderr monitoring.',
    );
  }
  const activeHostToolRelay = hostToolRelay;
  if (activeHostToolRelay == null) {
    throw new Error('The host tool MCP relay is unavailable.');
  }
  if (start.recoveryMode?.type === 'lossy-rerun') {
    const marker = {
      type: 'acp-recovery',
      mode: 'lossy-rerun',
      reason: start.recoveryMode.reason,
    } as const;
    turn.emit({ type: 'raw', rawValue: marker });
    turn.bridgeLog({
      level: 'warn',
      subsystem: 'acp.recovery',
      message:
        'The ACP process was replaced; the original prompt is being rerun against the resumed ACP session.',
      attrs: marker,
    });
    turn.emitWarning({
      message:
        'ACP process-loss recovery is rerunning the interrupted prompt and may repeat work.',

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Ensure the environment allows binding an HTTP server on 127.0.0.1 (check firewall/sandbox/container networking rules).
2. Look for earlier relay startup errors in logs (port allocation or server 'error' events) and fix the underlying cause.
3. Retry after resolving resource/network issues; if it persists without an environment cause, report as a bridge bug.

const canBindLoopback = await new Promise<boolean>(resolve => {
  const s = new Server();
  s.once('error', () => resolve(false));
  s.listen(0, '127.0.0.1', () => s.close(() => resolve(true)));
});
if (!canBindLoopback) throw new Error('Loopback listener unavailable for host tool relay');

try {
  await bridge.runTurn({ prompt });
} catch (error) {
  if (error instanceof Error && error.message.includes('host tool MCP relay is unavailable')) {
    // check environment for socket-binding restrictions, then retry or recreate bridge
  }
  throw error;
}

When it happens

Trigger: The hostToolRelay variable is null at the point in runTurn where the turn starts — the relay HTTP server was never constructed, or its startup failed without surfacing, e.g. the loopback listener on 127.0.0.1 could not be bound.

Common situations: System restrictions blocking binding a loopback socket (strict firewalls, containers without networking, restricted sandboxes); resource exhaustion preventing server startup; a bridge bug skipping relay creation; running in an environment where ephemeral port listeners are disallowed.

Related errors

• Invalid host tool catalog poll response.
• ${readErrorMessage({ value, status: response.status })}
• ACP MCP server ${JSON.stringify(name)} must be configured wi
• ACP-transport MCP servers require client-side mcp/connect ha
• The ACP implementation did not load the active harness-owned

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/d6aa3700c910c2a2. Report an issue: GitHub.