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
| Name | Label | Transport | Config written |
|---|---|---|---|
claude | Claude Code | HTTP | claude mcp add --transport http --scope user, falling back to ./.mcp.json |
cursor | Cursor | stdio | ~/.cursor/mcp.json |
codex | Codex CLI | stdio | [mcp_servers.agentproto] in ~/.codex/config.toml |
claude-desktop | Claude Desktop | stdio | ~/Library/Application Support/Claude/claude_desktop_config.json (macOS only) |
aider | Aider | stdio | mcp_servers in ~/.aider.conf.yml |
windsurf | Windsurf | stdio | ~/.codeium/windsurf/mcp_config.json |
hermes | Hermes | HTTP | mcp_servers.agentproto in ~/.hermes/config.yaml |
opencode | OpenCode | HTTP (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 exits2; with no--agent, unsupported detected ones are left out silently (unlike--app, no "Skipping" note is printed), and when none is left the verb printsNo scoped-capable agents detected. Nothing to do.and exits0. - Exclusions: cannot be combined with
--app(exit2) or--dry-run(exit2). - 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/--uninstallact on it precisely, exactly like an--appentry.
Flags
| Flag | Default | Description |
|---|---|---|
--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). |
--yes | false | Non-interactive. Also authorises the background agentproto serve fallback when the daemon can't be started via daemon start. |
--dry-run | false | Print 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-daemon | false | Skip daemon discovery/start; take the port from ~/.agentproto/config.json (daemon.port, default 18790). |
--update | false | Re-run registration for previously-registered agents — e.g. after a port change. Agents no longer detected are skipped, not removed. |
--uninstall | false | Remove 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:
- Discover via
~/.agentproto/runtime.jsonand probe/health. - Otherwise try
agentproto daemon start(launchd/systemd) and poll/healthfor 5s. - With
--yesonly, spawn a detachedagentproto serveand poll/healthfor 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 --yesRestart your CLI agent(s) afterwards to pick up the change — the verb reminds you when it registered or removed anything.
See also
onboard.md— first-run umbrella: this verb plus the skill packmcp-bridge.md— the stdio proxy the full-daemon registrations invokemcp-app.md— the stdio proxy--appregistrations invokeserve.md— the daemon hosting/mcp- Use agentproto as an MCP server inside coding CLIs — doing it by hand