Status: accepted · ADR-18 · Filed 2026-04-19
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.
