Verbs

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.

FlagDefaultDescription
--applyoff (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_TOKEN

When 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).

ExitMeaning
0Dry run, nothing to move, or every value moved.
1--apply finished with at least one warning (some key stayed literal).
2Bad 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:

  1. creates the bundle harness-<adapter> with the given ids as its mcpImports, or appends the new ids to it if it already exists;
  2. lists that bundle in defaults.adapters.<adapter>.bundles in ~/.agentproto/config.json (if not already listed).
ArgumentDescription
<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.

ExitMeaning
0Bundle and config are in the desired state.
1Rejected input (bad adapter slug, unknown import id) or a failed write.
2Missing <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:

  1. discovers the server and registers a client;
  2. prints the authorization URL and the requested scopes, then waits on a one-shot 127.0.0.1 loopback listener (opens a browser unless --no-open);
  3. stores the client + tokens as one OS-keychain item per import — never in imported-mcps.json;
  4. verifies with tools/list, and only then records auth: { type: "oauth" } on the import.
FlagDefaultDescription
--url <url>—Create a manual http import when the alias is unknown.
--scope "a b"server defaultSpace-separated OAuth scopes to request.
--no-openoffPrint the URL without opening a browser.
--timeout <duration>5mHow long to wait for the consent (90s, 30m, 2h; a bare number is seconds). Min 10s, max 2h; anything else is rejected.
--manual (--paste)offAlso 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, …
ExitMeaning
0Login verified (or logout completed).
1Consent failed, verification failed, or the import is not a remote MCP.
2Missing <alias|importId> / a flag needs a value / unexpected option.

See also

  • settings.md — exports/imports imported-MCP pointers between machines
  • install-mcp.md — registers the daemon's MCP server with coding CLIs
  • mcp-bridge.md — stdio proxy to the daemon /mcp endpoint