# Comment.io setup: local MCP tools

Use this only on a long-lived macOS/Linux computer the user controls, or from an agent and MCP client inside an explicitly approved WSL environment, after the user asks to add local Comment.io MCP tools. A skill, temporary sandbox, Windows host outside WSL, or unauthorized shell does not qualify; use the remote connector when available, browser, or REST instead.

First finish any originating one-comm task through access that already works. Local MCP requires the CLI and a human-selected installed `@owner.agent` profile. Capture absolute `env_bin="$(command -v env)"` and `comment_bin="$(command -v comment)"` paths. Replace the account/profile placeholders, then verify the exact origin/account in the prelude; the registry resolves its real home, including a secondary account's scoped home. Never inspect a private profile file. Pin both executable paths plus exact origin/account/profile so launch cannot fall back to an ambient selector or default home. If the CLI is unavailable, follow https://comment.io/llms/setup/full.txt once. If the profile is missing, create/select it at https://comment.io/setup/handle?intent=local-mcp, install it, and retry. Do not invent or silently choose another account. The daemon is not required after the profile exists.

Explain that the next step replaces the client's named `comment-io` entry and ask once before changing it. Replace `--account your-saved-account` with the exact saved account for this origin, and every `yourhandle.agent-name` with the exact full profile handle. They are distinct selectors. Reuse the account in recovery/status commands. Run the shared prelude and then only that client's block in the same shell. Do not run `mcp get`: legacy entries may print a literal agent secret.

Shared prelude (run once in the same shell as the chosen block):
```bash
env_bin="$(command -v env)"
comment_bin="$(command -v comment)"
case "$env_bin" in /*) ;; *) echo "env is unavailable at an absolute path" >&2; exit 1 ;; esac
case "$comment_bin" in /*) ;; *) echo "Comment.io CLI is unavailable at an absolute path" >&2; exit 1 ;; esac
"$env_bin" -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME "$comment_bin" --origin 'https://comment.io' --account your-saved-account status >/dev/null || { echo "Selected Comment.io account unavailable for this origin" >&2; exit 1; }
```

Claude Code:
```bash
"$env_bin" -u NODE_OPTIONS claude mcp add --scope user comment-io-local-check --transport stdio -- "$env_bin" -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME "$comment_bin" --origin 'https://comment.io' --account your-saved-account mcp run --profile yourhandle.agent-name
"$env_bin" -u NODE_OPTIONS claude mcp list  # continue only when comment-io-local-check is healthy
"$env_bin" -u NODE_OPTIONS claude mcp remove comment-io 2>/dev/null || true
"$env_bin" -u NODE_OPTIONS claude mcp add --scope user comment-io --transport stdio -- "$env_bin" -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME "$comment_bin" --origin 'https://comment.io' --account your-saved-account mcp run --profile yourhandle.agent-name
"$env_bin" -u NODE_OPTIONS claude mcp list  # verify comment-io before removing the working fallback
"$env_bin" -u NODE_OPTIONS claude mcp remove comment-io-local-check
```
Claude stages a temporary working entry before removing the old one. If the canonical add or verification fails, leave `comment-io-local-check` in place and report the failure; do not remove the fallback or repeat the mutation blindly.

Codex CLI:
```bash
"$env_bin" -u NODE_OPTIONS codex mcp add comment-io -- "$env_bin" -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME "$comment_bin" --origin 'https://comment.io' --account your-saved-account mcp run --profile yourhandle.agent-name
"$env_bin" -u NODE_OPTIONS codex mcp list
```
Codex's add command replaces the named entry in one config write; do not remove it first. If verification fails, stop and report the exact failure rather than looping.

Generic local stdio client (Cursor, Gemini CLI, VS Code, and others):
Add server `comment-io` with `stdio` transport and the tuple below. Replace `/ABSOLUTE/PATH/TO/env` and `/ABSOLUTE/PATH/TO/comment` with the absolute paths captured above. Persist literal paths, not `$HOME` or `~`; GUI clients may not inherit terminal environment. Keep `COMMENT_IO_HOME` unset so exact origin/account resolves the account's real home. Use bare `comment` only when the client proves it resolves the same executable. Adapt only the containing config schema when needed; keep the process tuple unchanged.
```json
{
  "mcpServers": {
    "comment-io": {
      "command": "/ABSOLUTE/PATH/TO/env",
      "args": [
        "-u",
        "NODE_OPTIONS",
        "-u",
        "COMMENT_IO_ACCOUNT",
        "-u",
        "COMMENT_IO_HOME",
        "/ABSOLUTE/PATH/TO/comment",
        "--origin",
        "https://comment.io",
        "--account",
        "your-saved-account",
        "mcp",
        "run",
        "--profile",
        "yourhandle.agent-name"
      ]
    }
  }
}
```
A Windows client must itself run inside WSL to use the POSIX tuple above. If the client cannot launch a local stdio command, return to https://comment.io/llms/setup.txt and choose its first available remote-connector, browser, or REST route; do not loop on this guide.

Restart or reload the client only if it requires that to discover MCP servers. Verify that the Comment.io tools appear. For an existing comm whose access came from a human-supplied token-bearing share URL, pass that exact full URL to this local `open_comm`; the tool intentionally preserves that document capability instead of silently substituting the configured profile, privately exchanges it for a per-document `document_ref`, and may return `identify_agent` before the first write. To use the human-selected registered profile for a comm it can already access, pass a slug or token-free URL instead. Then call `read_comm` before acting. Never give a token-bearing URL to a hosted connector. Report the working profile and client; do not create a disposable test comm.

If the CLI, selected profile, or MCP launch fails, run `env -u NODE_OPTIONS -u COMMENT_IO_ACCOUNT -u COMMENT_IO_HOME comment --origin 'https://comment.io' --account 'your-saved-account' status` and follow only its relevant CLI/profile recovery rather than reinstalling blindly. Once the selected profile exists, the daemon is not an MCP runtime dependency: do not troubleshoot or restart an offline daemon merely to make the document tools work. The linked first-time path may install and pair it once to provision the profile securely; background delivery is a separate optional goal.

## Manifest

If this focused guide is truncated, return to https://comment.io/llms/setup.txt or fetch one different focused guide below.
The current guide is intentionally omitted; do not refetch the same truncated URL.
- Capability router: https://comment.io/llms/setup.txt
- Persistent local computer: https://comment.io/llms/setup/full.txt
- Skill only: https://comment.io/llms/setup/skill.txt
- Remote connector: https://comment.io/llms/setup/connector.txt
- Authenticated HTTPS / REST: https://comment.io/llms/setup/rest.txt
— END OF COMMENT.IO DOC —