Skip to main content

​
Host Contract

What prism install promises to the MCP server runtime, and what runtime is allowed to assume.

​
Core principle

Cross-platform is a core tenant of Prism. Prism-the-process (MCP server) detects its OS at runtime. Prism-the-project (the codebase) must ship code that runs correctly on macOS, Linux, and Windows.
The install does all host detection once, at install time, and writes the results into each editor’s MCP env block. Runtime reads env. This eliminates detection drift between install and runtime, and between different agents running against the same install.

​
What install writes into each editor’s MCP env block

VariableSource at installConsumed by
PRISM_API_URLpersonal default / LAN / cloud argbackend client
PRISM_API_KEY~/.prism/credentials.personal.json or argbackend client
PRISM_ROOTbootstrap script locationpath resolution, scaffold lookups
PROJECT_ROOT$PROJECT_ROOT env or ~/projectsprism_clone, prism_create default dir
PRISM_GITHUB_USERgit config --global user.name or askedprism_clone auto-derive of github_repo
PRISM_HOST_OSplatform.system() normalizededitor config path resolution
PRISM_APP_SUPPORTper-OS config rooteditor config path resolution
PRISM_FS_MCP_NAMEdefault projects-filesystemfilesystem MCP block name
LOG_DIR$PRISM_ROOT/logslog file writes

​
What runtime is allowed to assume

  1. PRISM_API_URL + PRISM_API_KEY are set and reachable via HTTP. If not, preflight warns; backend calls fail cleanly.
  2. PROJECT_ROOT is writable by the user running the MCP server.
  3. PRISM_HOST_OS is one of darwin, linux, win32. If unset, runtime falls back to live platform.system() and logs the gap.
  4. PRISM_GITHUB_USER is a valid GitHub handle (no spaces, no slashes). If unset, prism_clone’s auto-derive attempts git config user.name live.
  5. Binaries on PATH: git, python3.11+, node (for npx of the filesystem MCP; only needed at editor-runtime, not install-time).

​
What runtime is NOT allowed to assume

  • A specific package manager (brew / winget / apt). That’s install’s concern; runtime never invokes them.
  • A specific Python other than 3.11+. The venv at mcp/.venv/bin/python (or Scripts\python.exe on Windows) is the interpreter; install set it up.
  • A specific shell. Runtime subprocesses use the binary directly (git, docker), never bash -c "..." style.
  • Internet access during normal tool calls (except git clone, which is explicit user intent and fails with a clear error if offline).

​
Host-side vs backend-side execution contract

ConcernRuns host-side (MCP server, Python)Runs backend-side (Docker container)
git operations (clone, init, remote, ls-remote)✓✗ — backend container has no git binary by design
Editor config file writes✓✗ — backend can’t see host filesystem
Filesystem MCP installation✓✗
Database writes (projects, todos, deltas, etc.)✗✓
Semantic recall (pgvector + tsvector + Neo4j)✗✓
PID minting✗✓
BIOS template composition (prism_sync_bios)✓ — composed host-side✗ — backend has no $PRISM_ROOT/templates/
Rule of thumb: if it touches the caller’s OS/filesystem/git/editors, it runs in the MCP server (Python, host-side). If it touches Prism’s data stores, it runs in the backend (Docker).

​
Backend deploy shapes

Three backend targets, all independent of host OS:
ModeWhatSet by
local (formerly “personal”)Docker Compose on the caller’s Mac/Linux/Winprism up + prism install --mode local (TS CLI)
lanDocker Compose on a home server (server1.home.lan)User runs bin/prism-server-install.sh there; clients run prism install --mode lan --api-key …
cloudHosted Prism service (deferred)Not yet available; planned flow is prism login + prism install --mode cloud
The MCP server’s only connection to the backend is PRISM_API_URL + PRISM_API_KEY. Backend never knows what OS the caller is on. That’s orthogonal to everything else.

​
Per-OS config file locations

Editors’ MCP config files — where install writes, runtime reads:
EditormacOSLinuxWindows
Claude Desktop~/Library/Application Support/Claude/claude_desktop_config.json~/.config/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.json
Claude Code~/.claude.json + ~/.claude/settings.jsonsame%USERPROFILE%\.claude.json + .claude\settings.json
Cursor~/.cursor/mcp.jsonsame%USERPROFILE%\.cursor\mcp.json
Codex~/.codex/config.tomlsame%USERPROFILE%\.codex\config.toml
If any of these change upstream (editor vendor moves the config), update the clients() function in cli/src/index.ts and re-run prism install. Runtime picks up the new path via whatever the TS CLI writes into each editor’s MCP block. (The legacy Python install/ tree is deprecated per the TS migration — do not add new client paths there.)

​
Re-running install when host state changes

The install manifest is pinned at install time. If any of these change, re-run prism install to refresh (idempotent, auto-detects existing backend, preserves user-added env keys unless --force is passed):
  • OS upgrade (Windows 10 → 11; macOS major version)
  • New editor installed (Codex was absent, now installed)
  • New git identity (git config --global user.name changed)
  • $PROJECT_ROOT relocated
Runtime won’t notice these automatically — by design. Re-install is cheap and idempotent.

​
Dev-side invariants

When adding new host-touching features:
  1. Never call platform.system() in runtime code. Use os.environ["PRISM_HOST_OS"].
  2. Never call Path.home() for config paths. Use PRISM_APP_SUPPORT / PROJECT_ROOT.
  3. Never assume a package manager. If install is wrong, fix it in install.
  4. Add any new host-dependent value to the install env block + this doc + the _startup_preflight() check list in mcp/server.py.
Last modified on April 24, 2026