Verbs

agentproto install-mcp

agentproto install-mcp [--agent <name>...] [--all] [--yes] [--dry-run]
                       [--skip-daemon] [--update] [--uninstall]
agentproto install-mcp --app <appId> [--agent <name>...] [--yes]
agentproto install-mcp --import <alias> [--agent <name>...] [--yes]

Register the daemon's MCP server with the coding-CLI agents installed on this machine. Detects which agents are present, ensures the daemon is running (or starts it), then writes the right MCP entry into each agent's own config file.

What it registered is tracked in ~/.agentproto/install-state.json, so --update and --uninstall act precisely on agentproto's own entries and never clobber MCP servers you added yourself.

Agents

NameLabelTransportConfig written
claudeClaude CodeHTTPclaude mcp add --transport http --scope user, falling back to ./.mcp.json
cursorCursorstdio~/.cursor/mcp.json
codexCodex CLIstdio[mcp_servers.agentproto] in ~/.codex/config.toml
claude-desktopClaude Desktopstdio~/Library/Application Support/Claude/claude_desktop_config.json (macOS only)
aiderAiderstdiomcp_servers in ~/.aider.conf.yml
windsurfWindsurfstdio~/.codeium/windsurf/mcp_config.json
hermesHermesHTTPmcp_servers.agentproto in ~/.hermes/config.yaml
opencodeOpenCodeHTTP (remote)mcp.agentproto in ~/.config/opencode/opencode.json

An agent counts as detected when its binary is on PATH or its config file/dir exists (windsurf, like cursor, has no relevant CLI binary — detection is config-path-only). stdio registrations run agentproto mcp-bridge (see mcp-bridge.md). They carry an AGENTPROTO_MCP_URL env var when the daemon isn't on the default port 18790; Claude Desktop always gets one, because its URL pins the shared Chat-tab identity: http://127.0.0.1:<port>/mcp?callerSessionId=claude-desktop&host=claude-desktop. Every Claude Desktop chat therefore shares one claude-desktop inbox, which is pull-only through inbox_list and labelled unverified (nothing proves a client that claims the id is Claude Desktop). Use the Code tab's daemon-spawned session when you need an attested identity.

Hermes is edited surgically — a real hermes config carries sibling MCP servers under mcp_servers:, so the entry is upserted in place and the file is backed up to config.yaml.bak first. If ~/.hermes/config.yaml doesn't exist yet, the step is skipped rather than synthesised: run hermes once, then re-run.

OpenCode is registered as a "remote" MCP entry ({type: "remote", url}) under the top-level mcp map of ~/.config/opencode/opencode.json — a merge, never a truncate, so any other config (provider keys, other mcp entries) survives. OpenCode merges every config source it loads rather than picking one exclusively (opencode.ai/docs/config/), so this is written even when a hand-maintained opencode.jsonc already exists alongside it; the two are additive.

--app <appId>: scoped registration for a book/library app

By default this verb registers the full daemon (agentproto mcp-bridge, every tool). --app <appId> instead writes agentproto mcp-app <appId> — the curated, one-app proxy (see mcp-app.md) — for an app that declares the book/library contract (category: "book" or a non-empty library.books in its APP.md frontmatter — a convention this CLI reads directly; app has no typed support for it). The app must already be installed (agentproto app install <dir>).

Only agents whose config format can hold multiple named MCP entries side-by-side support --app: cursor, codex, claude-desktop, windsurf. claude/hermes register over HTTP through a different mechanism, and aider's writer assumes agentproto is its only MCP entry (a full-file remove-and-replace, not a surgical per-key edit) and would silently drop siblings — all three are refused: an explicitly-requested unsupported agent (--agent claude --app <id>) exits 2; with no --agent (all detected), unsupported ones are silently skipped with a note.

A scoped entry is written under its own key (agentproto-app-<appId>/[mcp_servers.agentproto-app-<appId>], appId sanitized to [A-Za-z0-9_-]), distinct from the full-daemon agentproto key — the two can coexist for the same client, and --update/--uninstall track them separately (the tracked state entry carries an appId).

--import <alias>: scoped registration for one imported MCP server

The same scoped mode for ONE imported MCP server (for example bureau): it writes an entry named after the alias that runs agentproto mcp-bridge --import <alias> (see mcp-bridge.md), so a stdio-only client (Codex app, Claude Desktop) sees that server's native tool names instead of the daemon's full tool set.

  • Agents: the same four as --app — cursor, codex, claude-desktop, windsurf. An explicitly-requested unsupported agent exits 2; with no --agent, unsupported detected ones are left out silently (unlike --app, no "Skipping" note is printed), and when none is left the verb prints No scoped-capable agents detected. Nothing to do. and exits 0.
  • Exclusions: cannot be combined with --app (exit 2) or --dry-run (exit 2).
  • Validation: the alias must look like bureau (letters, digits, . _ -) — but it is NOT checked against the daemon here; the bridge and the daemon resolve it when the client starts.
  • Tracked state: the entry carries an importAlias, so --update/--uninstall act on it precisely, exactly like an --app entry.

Flags

FlagDefaultDescription
--agent <name>(all detected)Target one agent; repeatable. Unknown names fail with exit 2; known-but-undetected ones exit 1.
--all—Target every detected agent — which is already the default. Accepted for explicitness, but it changes nothing: with --agent also present, --agent wins and --all is ignored.
--app <appId>—Scoped mode — see above. Requires the app to be installed and declare the book/library contract; exits 1 otherwise.
--import <alias>—Scoped mode for one imported MCP server — see above. Writes an entry named <alias> running agentproto mcp-bridge --import <alias>; supported agents cursor, codex, claude-desktop, windsurf. Cannot be combined with --app or --dry-run (exit 2).
--yesfalseNon-interactive. Also authorises the background agentproto serve fallback when the daemon can't be started via daemon start.
--dry-runfalsePrint the exact MCP entry as JSON on stdout and write nothing (no config file, install state or daemon start). Only for the claude-desktop target; exits 2 with --app, and prints nothing when Claude Desktop is not a target.
--skip-daemonfalseSkip daemon discovery/start; take the port from ~/.agentproto/config.json (daemon.port, default 18790).
--updatefalseRe-run registration for previously-registered agents — e.g. after a port change. Agents no longer detected are skipped, not removed.
--uninstallfalseRemove only the entries listed in install-state.json, then clear it.

Daemon bootstrap

Unless --skip-daemon is passed, the verb resolves a live daemon before writing any config, since the port it registers has to be the real one:

  1. Discover via ~/.agentproto/runtime.json and probe /health.
  2. Otherwise try agentproto daemon start (launchd/systemd) and poll /health for 5s.
  3. With --yes only, spawn a detached agentproto serve and poll /health for 10s.

If none of those land, nothing is registered and the verb exits 1 telling you to run agentproto serve manually.

Examples

# Wire every detected agent, non-interactive
agentproto install-mcp --yes

# Just Claude Code and Codex
agentproto install-mcp --agent claude --agent codex

# Re-point existing registrations after `config set daemon.port 18791`
agentproto install-mcp --update

# Print the entry Claude Desktop would get, without touching its config
agentproto install-mcp --dry-run --agent claude-desktop

# Back out everything agentproto added
agentproto install-mcp --uninstall

# Scope a buyer-facing entry to one installed book app instead of the full daemon
agentproto install-mcp --app my-book --agent cursor --yes

# Register one imported MCP server (native tool names) for Codex and Claude Desktop
agentproto install-mcp --import bureau --agent codex --agent claude-desktop --yes

Restart your CLI agent(s) afterwards to pick up the change — the verb reminds you when it registered or removed anything.

See also