> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# ADR-18: MCP config hostnames must be FQDNs (not bare) on macOS

> PRISM_API_URL in every editor's MCP env block must use a fully-qualified domain name (e.g., server1.home.lan) — never a bare hostname (server1). Applies to Clau

<Info>**Status:** `accepted` · **ADR-18** · Filed 2026-04-19</Info>

## Decision

PRISM\_API\_URL in every editor's MCP env block must use a fully-qualified domain name (e.g., server1.home.lan) — never a bare hostname (server1). Applies to Claude Desktop, Claude Code, Cursor, Codex configs across all platforms; the macOS case is the forcing one but FQDN is the safe default everywhere.

## Rationale

macOS GUI applications launched via launchd (Claude Desktop, etc.) do NOT inherit the shell's resolver search-domain list (e.g., 'search home.lan' from the router). A bare hostname that resolves from Terminal — because zsh/bash applies the search suffix — fails to resolve inside the MCP subprocess spawned by the GUI app. Symptom: 'All connection attempts failed' in MCP log; agent falls back to offline mode. Observed 2026-04-18 during Wave 4B server1 cutover: server1 curl'd fine from Terminal, failed from Claude Desktop MCP. Fixed by switching 4 configs to server1.home.lan. Generalizes beyond macOS: FQDNs resolve identically across Terminal, GUI, Windows, Linux — never depend on resolver search-path inheritance.

## Alternatives Considered

(a) Add /etc/hosts entry on every Mac — requires sudo, brittle, doesn't cover IP changes. (b) Use raw IP — brittle if LAN/DHCP changes. (c) Leave bare hostname and document the macOS trap — violates AI-FIRST (forces human to diagnose the same confusion again). FQDN chosen: zero-friction, platform-independent, self-documenting.