agentproto mcp
agentproto mcp migrate-secrets [--apply]
agentproto mcp mount-default <adapter> <importId...>
agentproto mcp login <alias|importId> [--url <url>] [--scope "a b"] [--no-open]
[--timeout <duration>] [--manual|--paste]
agentproto mcp logout <alias|importId>Maintenance for imported MCPs — the MCP server pointers recorded in
~/.agentproto/imported-mcps.json (see settings.md, which
carries them between machines). migrate-secrets and mount-default operate
on local files only and need no running daemon; login/logout manage the
OAuth credential for a remote import.
Not to be confused with mcp-bridge / mcp-app,
which are stdio MCP servers, or install-mcp, which registers
the daemon's own MCP server with coding CLIs.
agentproto mcp, agentproto mcp --help, -h and help print the usage text
and exit 0. An unknown subcommand prints the usage to stderr and exits 2.
migrate-secrets
Moves literal header and env values in imported-mcps.json behind OS-keychain
references (secretRefs), so the file no longer holds the secrets in clear.
| Flag | Default | Description |
|---|---|---|
--apply | off (dry run) | Actually store the values and rewrite the file. Without it nothing is written. |
Never automatic — you run it, per machine.
Dry run (default) lists what would move, by key name only — values are never printed:
Would move to keychain (dry run — nothing written; pass --apply):
github: headers.Authorization
my-server: env.API_KEY, env.OTHER_TOKENWhen nothing is literal: No literal header/env values to move.
--apply works per key: the keychain write happens first and is read back
to verify; only then is the value in the snapshot replaced by the
<secretRef> marker. The file is rewritten once, atomically, at the end.
A key that fails verification stays literal and is reported as a
warning: on stderr. Ends with <n> value(s) moved.
Any other argument exits 2 (unexpected argument).
| Exit | Meaning |
|---|---|
0 | Dry run, nothing to move, or every value moved. |
1 | --apply finished with at least one warning (some key stayed literal). |
2 | Bad arguments / unknown subcommand. |
mount-default
agentproto mcp mount-default <adapter> <importId...>Makes every future spawn of <adapter> mount the given imported MCPs
natively (a real mcpServers entry), instead of only being reachable through
the daemon gateway. It:
- creates the bundle
harness-<adapter>with the given ids as itsmcpImports, or appends the new ids to it if it already exists; - lists that bundle in
defaults.adapters.<adapter>.bundlesin~/.agentproto/config.json(if not already listed).
| Argument | Description |
|---|---|
<adapter> | Adapter slug, lowercase kebab-case (^[a-z0-9][a-z0-9-]*$). |
<importId...> | One or more ids from imported-mcps.json. Every id must already be imported; unknown ids are rejected with the list of valid ones. |
Opt-in per adapter — nothing is mounted natively by default. Repeat the
command to add more ids. If harness-<adapter> already exists as a wildcard
bundle (mcpImports: "*"), it is left unchanged.
bundle harness-codex: created (+github, linear)
defaults.adapters.codex.bundles: linked
New 'codex' spawns mount these natively; running sessions are unchanged.The first line reads created, updated (ids added) or unchanged; the
second reads linked or already linked. Running sessions are not affected.
| Exit | Meaning |
|---|---|
0 | Bundle and config are in the desired state. |
1 | Rejected input (bad adapter slug, unknown import id) or a failed write. |
2 | Missing <adapter> / <importId...>, or an argument starting with -. |
login / logout
agentproto mcp login <alias|importId> [--url <url>] [--scope "a b"] [--no-open]
[--timeout <duration>] [--manual|--paste]
agentproto mcp logout <alias|importId>Remote (http/sse) MCPs that accept no API key or static header can
authenticate with OAuth 2.1 (RFC 9728 resource-metadata discovery, RFC 7591
dynamic client registration, PKCE). login runs the whole consent:
- discovers the server and registers a client;
- prints the authorization URL and the requested scopes, then waits on a
one-shot
127.0.0.1loopback listener (opens a browser unless--no-open); - stores the client + tokens as one OS-keychain item per import — never
in
imported-mcps.json; - verifies with
tools/list, and only then recordsauth: { type: "oauth" }on the import.
| Flag | Default | Description |
|---|---|---|
--url <url> | — | Create a manual http import when the alias is unknown. |
--scope "a b" | server default | Space-separated OAuth scopes to request. |
--no-open | off | Print the URL without opening a browser. |
--timeout <duration> | 5m | How long to wait for the consent (90s, 30m, 2h; a bare number is seconds). Min 10s, max 2h; anything else is rejected. |
--manual (--paste) | off | Also accept the callback URL pasted on stdin (see below). |
Manual mode. When the browser is on another machine (SSH, remote box), the
loopback redirect can't reach the listener. After consent the browser lands on
an error page at http://127.0.0.1:PORT/callback?code=…&state=…; with
--manual, paste that full URL on stdin. The listener stays open in parallel
(the registered redirect_uri is still the listener's), so whichever arrives
first finishes the login. The state is checked against the one this login
generated; a URL without a code or with a wrong state is refused. The consent
URL that login prints does carry a state (it is meant to be opened); what
is never printed is the pasted callback URL, the authorization code and the
tokens. The URL is read from stdin only: the state is fresh per login, so a
URL can't be supplied up front as a flag. If stdin is closed (non-interactive
shell) the paste path just stays idle and the loopback listener keeps waiting.
The import must already be a remote (http/sse) MCP, or be creatable via
--url. Stored state is bound to the server origin, so a live-repointed
import never receives tokens.
The daemon refreshes tokens on its own and never starts an interactive flow:
when credentials are missing or revoked it fails with
oauth login required … run: agentproto mcp login <alias>.
logout forgets the stored OAuth state (the keychain item) for the named
import; the import entry itself is left in place.
Logged in: qonto (manual:cli:qonto) — import created
Granted scopes: accounts
3 tool(s): list_accounts, get_balance, …| Exit | Meaning |
|---|---|
0 | Login verified (or logout completed). |
1 | Consent failed, verification failed, or the import is not a remote MCP. |
2 | Missing <alias|importId> / a flag needs a value / unexpected option. |
See also
settings.md— exports/imports imported-MCP pointers between machinesinstall-mcp.md— registers the daemon's MCP server with coding CLIsmcp-bridge.md— stdio proxy to the daemon/mcpendpoint