# Host Installation

ITHZ-MCP exposes a local stdio MCP server. Host integrations should start in read-only mode.

Normal startup profile:

```powershell
python -m ithz_mcp mcp-server --project <project> --mode read-only --protocol mcp --storage-profile native-archive
```

Explicit write profile:

```powershell
python -m ithz_mcp mcp-server --project <project> --mode write-enabled --protocol mcp --storage-profile native-archive
```

Use the write-enabled profile only for end-of-task memory writes. The read-only profile is the normal startup profile.

On macOS and Linux, the same MCP server runs through Python stdio. The product package includes `ithz_mcp_server.sh` and POSIX host installer scripts. macOS configs default to `--storage-profile legacy` unless a compatible macOS `ithz-native` binary is supplied.

In generated host configs, the write-enabled profile exposes `ithz_archive_auto_checkpoint` plus typed durable instruction and Project Ledger write tools. The server `initialize` response tells compatible hosts to call the checkpoint tool at the end of a completed task before the final answer, unless the user opts out or there is nothing durable to store. If the user gives a lasting workflow rule, project decision, validation gate, must-not-break rule, scoped claim, blocked claim, reviewer note or replication-pack result, the host should call the matching durable tool before finishing. This keeps the write automatic as part of the agent workflow, while the actual write remains an explicit MCP call into `project.ithz`.

Read-only configs can still call ledger inspection tools such as `ithz_can_i_claim` and `ithz_get_project_ledger_summary`; they cannot create or modify ledger records.

## Generate Installers

```powershell
python -m ithz_mcp write-host-installers --project <project> --out host_installers
```

This creates:

- `codex_mcp_config.sample.json`
- `codex_config_snippet.toml`
- `claude_code_mcp_config.sample.json`
- `cursor_mcp_config.sample.json`
- `antigravity_mcp_config.sample.json`
- `generic_mcp_config.sample.json`
- `install_codex_mcp.ps1`
- `install_claude_code_mcp.ps1`
- `install_cursor_mcp.ps1`
- `install_antigravity_mcp.ps1`
- `install_codex_mcp.sh`
- `install_claude_code_mcp.sh`
- `install_cursor_mcp.sh`
- `install_antigravity_mcp.sh`

The PowerShell install scripts default to dry-run. Pass `-Apply` only after reviewing the generated config.

The POSIX install scripts default to dry-run. Pass `--apply` only after reviewing the generated config.

The product package also contains a dedicated `host_installers_macos/` folder generated with the portable `ithz_mcp_server.sh` launcher and legacy storage profile for macOS compatibility.

## Validate

```powershell
python -m ithz_mcp mcp-config-validate --config host_installers\codex_mcp_config.sample.json
python -m ithz_mcp mcp-client-smoke --config host_installers\codex_mcp_config.sample.json
```

`mcp-client-smoke` is a scripted stdio client. It validates the MCP protocol surface, request IDs, invalid request handling, tool calls and response limits. A real host UI smoke should still be done per host after installing config.

## Host Notes

- Codex can use the generated TOML snippet in `~/.codex/config.toml`.
- Claude Code can use the generated `.mcp.json` style config or host-specific MCP add flow.
- Cursor can use a project `.cursor/mcp.json` style config.
- Antigravity can use the generated project-level MCP config if the host supports project MCP configuration.

Host products can change their config format. Treat the generated files as validated local templates, not a claim that every external host version has been certified.

Read-only and write-enabled profiles are intentionally separate. A host that should never write memory should only enable the read-only profile.

For macOS package usage, see `docs/MACOS_MCP_SETUP.md`.

For Ubuntu/Linux package usage, see `docs/UBUNTU_MCP_SETUP.md`. The Ubuntu package includes a user-local `install.sh`, a `.deb` package, Linux host installer scripts, scripted smoke checks, a Linux `ithz-native` source build kit, and extraction-backed fallback commands (`ithz-verify`, `ithz-list`, `ithz-extract-here`, `ithz-open-temp`). It defaults to legacy storage unless a compatible Linux `ithz-native` binary is supplied or built on the Ubuntu host. Full Linux Drive/FUSE support is not bundled yet.
