hx-cli 0.2.5__tar.gz → 0.2.6__tar.gz

{hx_cli-0.2.5 → hx_cli-0.2.6}/CHANGELOG.md

@@ -28,6 +28,53 @@ the project follows [semantic versioning](https://semver.org/).
 
 ---
 
+## [0.2.6] - 2026-09-23
+
+### Added
+
+- Sign in to remote MCP servers over OAuth. A server that asks for it -
+  Atlassian's `https://mcp.atlassian.com/v2/mcp`, for one - shows as needing
+  sign-in; `/mcp login <server>` or `hx mcp login <server>` opens the browser
+  and the tools arrive without a restart. Tokens refresh on their own;
+  `/mcp logout <server>` forgets them. `"oauth": {"clientId": ...}` in
+  `mcp.json` covers servers without client registration.
+- MCP servers that change their tool list mid-session have the new list
+  swapped in, whether they announce it in a reply or on their own stream.
+- `hx mcp add NAME --url URL --header "Name: value"` saves headers, such as an
+  API token, with the server.
+- `/mcp reconnect <server>` restarts one server without restarting HX.
+- `/resume` always offers a list to switch to: this directory's sessions
+  first, then every other directory's, each row naming where it lives.
+  Picking one from elsewhere restarts HX in that directory on it, with the
+  same `--mode` and `--model`. The session already open is no longer listed,
+  and the list is no longer cut at 20.
+
+### Fixed
+
+- `/resume` said "No previous sessions in this directory" in a fresh
+  directory, or inside a session resumed from another one, instead of
+  listing anything.
+- `hx resume <id>` ran the session in whatever directory you typed it in,
+  not the one it was recorded in, so its paths and tool calls pointed at the
+  wrong project.
+- `hx mcp add NAME --url URL`, `--user`, and server arguments like `npx -y`
+  were refused as unknown options, so none of them could be run.
+- `hx mcp add` dropped headers from the entry it wrote.
+- A remote MCP server that expires its session is initialized again instead
+  of failing every call until HX restarts.
+- A multi-line shell command no longer breaks the screen. Its approval shows
+  one row per line, the tool call shows the first line and `+N lines`
+  (`ctrl+o` shows the rest), and the approval options and prompt are no longer
+  drawn several times over.
+- `/resume` from inside a resumed session showed the resumed conversation
+  pushed off the top of the screen, leaving only the "Resumed" notice.
+- A session title with a line break in it no longer splits its row in the
+  `/resume` picker.
+- Started in your home directory, the status bar named it `~/.`; it now reads
+  `~`.
+
+---
+
 ## [0.2.5] - 2026-09-23
 
 ### Added
@@ -592,7 +639,8 @@ First release, published to PyPI as [`hx-cli`](https://pypi.org/project/hx-cli/)
 - `/configure` and `hx auth` for the OpenRouter key, `hx upgrade` for
   self-update, and `install.sh` bootstrapping uv with a pinned Python.
 
-[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.5...HEAD
+[Unreleased]: https://github.com/aletisunil/hx/compare/v0.2.6...HEAD
+[0.2.6]: https://github.com/aletisunil/hx/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/aletisunil/hx/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/aletisunil/hx/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/aletisunil/hx/compare/v0.2.2...v0.2.3

{hx_cli-0.2.5 → hx_cli-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hx-cli
-Version: 0.2.5
+Version: 0.2.6
 Summary: HX - an agent harness for the terminal
 Project-URL: Homepage, https://hx.sunilaleti.dev
 Project-URL: Documentation, https://hx.sunilaleti.dev
@@ -299,7 +299,7 @@ hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
 hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 hx resume                   # resume the last session here
-hx resume <session-id>      # resume a specific one
+hx resume <session-id>      # resume a specific one, in the directory it was recorded in
 hx prompt                   # print the system prompt this directory would use
 hx trace                    # write the last session here to an HTML page
 hx trace out.html           # the same, to a path you choose
@@ -311,6 +311,8 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp login <server>       # sign in to a remote MCP server in the browser
+hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
 hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
@@ -478,14 +480,14 @@ than being silently resolved.
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session, listed by name |
+| `/resume` | switch to another session - this directory's first, then the rest |
 | `/rewind` | go back to an earlier prompt, restoring the files HX changed |
 | `/title [text]` | show or set this session's name |
 | `/prompt` | the system prompt this session is running with |
 | `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
-| `/mcp` | server status |
+| `/mcp [login\|logout\|reconnect <server>]` | server status, and signing in to remote servers |
 | `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
@@ -701,6 +703,13 @@ if you want a cheaper model for it — and it is counted in `/cost` like any oth
 If the call fails the session is still named, from your first message. `/title
 <text>` renames it.
 
+`/resume` lists every session except the one you are in: this directory's
+first, then other directories', each row naming where it lives. A session from
+this directory is swapped in place. One from elsewhere belongs to that
+directory - its sandbox, permission rules, prompt and tools - so HX restarts
+itself there with `hx resume <id>`, keeping options like `--mode` and
+`--model`.
+
 ### Themes
 
 A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
@@ -996,10 +1005,41 @@ construction.
 }
 ```
 
-Or `hx mcp add local python server.py`. Tools arrive namespaced
+Or `hx mcp add local python server.py`, or
+`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
-dropped rather than taking the session with it.
+dropped rather than taking the session with it. A server that changes its tool
+list mid-session (`notifications/tools/list_changed`) has the new list swapped
+in without a restart.
+
+A remote server that asks for sign-in - Atlassian's, for one - is signed in to
+over OAuth, with nothing to configure:
+
+```json
+{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }
+```
+
+It shows as needing sign-in until you run `/mcp login atlassian` in a session
+or `hx mcp login atlassian` in a shell. That opens the browser, and the tools
+arrive as soon as you approve - no restart. HX follows the MCP authorization
+spec: it finds the authorization server from the server's metadata, registers
+itself as a client, signs in with PKCE, and keeps the token in `~/.hx/auth.json`
+(mode 0600), refreshing it before it expires and again if the server rejects
+it. Over SSH, paste the final redirect URL into the prompt instead.
+`/mcp logout atlassian` forgets it.
+
+A server that does not offer client registration needs a client you register
+with it yourself, and anything else about the sign-in can be pinned the same
+way:
+
+```json
+"oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write", "callbackPort": 33418 }
+```
+
+To send a token of your own instead - an API key - give the server an
+`Authorization` header, and OAuth stays out of the way:
+`hx mcp add jira --url https://mcp.atlassian.com/v2/mcp --header "Authorization: Basic <base64 email:token>"`.
 
 **Hooks** are shell commands HX runs at named points in a turn. Four events:
 `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.

{hx_cli-0.2.5 → hx_cli-0.2.6}/README.md

@@ -259,7 +259,7 @@ hx                          # interactive TUI in the current directory
 hx -p "explain this repo"   # headless: streams to stdout, tool activity to stderr
 hx -p "why?" --image s.png  # attach an image to a headless prompt; repeatable
 hx resume                   # resume the last session here
-hx resume <session-id>      # resume a specific one
+hx resume <session-id>      # resume a specific one, in the directory it was recorded in
 hx prompt                   # print the system prompt this directory would use
 hx trace                    # write the last session here to an HTML page
 hx trace out.html           # the same, to a path you choose
@@ -271,6 +271,8 @@ hx --no-sandbox             # disable OS sandboxing (rules still apply)
 hx --system-prompt @p.md    # replace the system prompt for one run
 hx --append-system-prompt "Always run the tests"   # add to it; repeatable
 hx mcp list|add|remove      # manage MCP servers
+hx mcp login <server>       # sign in to a remote MCP server in the browser
+hx mcp logout <server>      # forget a remote MCP server's sign-in
 hx auth [set|clear]         # manage the OpenRouter key
 hx auth login [provider]    # sign in (openrouter, openai-codex, devin)
 hx auth logout <provider>   # forget a stored credential
@@ -438,14 +440,14 @@ than being silently resolved.
 | `/cost` | tokens, cache savings, spend |
 | `/compact [focus]` | summarise older turns now |
 | `/clear` | fresh session, same directory |
-| `/resume` | reopen a previous session, listed by name |
+| `/resume` | switch to another session - this directory's first, then the rest |
 | `/rewind` | go back to an earlier prompt, restoring the files HX changed |
 | `/title [text]` | show or set this session's name |
 | `/prompt` | the system prompt this session is running with |
 | `/todos` | show the current plan |
 | `/skills` | installed skills |
 | `/agents` | subagent types |
-| `/mcp` | server status |
+| `/mcp [login\|logout\|reconnect <server>]` | server status, and signing in to remote servers |
 | `/hooks` | configured hooks, and any that were refused |
 | `/theme [name]` | `dark`, `light`, `ansi`, or any theme in `~/.hx/themes` |
 | `/queue [steer <n>\|clear]` | messages waiting for the turn to end, and what to do with them |
@@ -661,6 +663,13 @@ if you want a cheaper model for it — and it is counted in `/cost` like any oth
 If the call fails the session is still named, from your first message. `/title
 <text>` renames it.
 
+`/resume` lists every session except the one you are in: this directory's
+first, then other directories', each row naming where it lives. A session from
+this directory is swapped in place. One from elsewhere belongs to that
+directory - its sandbox, permission rules, prompt and tools - so HX restarts
+itself there with `hx resume <id>`, keeping options like `--mode` and
+`--model`.
+
 ### Themes
 
 A theme is a JSON file: a `vars` block of raw colours, and a `colors` block
@@ -956,10 +965,41 @@ construction.
 }
 ```
 
-Or `hx mcp add local python server.py`. Tools arrive namespaced
+Or `hx mcp add local python server.py`, or
+`hx mcp add remote --url https://example.com/mcp`. Tools arrive namespaced
 `mcp__<server>__<tool>` in a deterministic order. Servers connect concurrently
 with a per-server timeout; one that is broken or slow logs a warning and is
-dropped rather than taking the session with it.
+dropped rather than taking the session with it. A server that changes its tool
+list mid-session (`notifications/tools/list_changed`) has the new list swapped
+in without a restart.
+
+A remote server that asks for sign-in - Atlassian's, for one - is signed in to
+over OAuth, with nothing to configure:
+
+```json
+{ "mcpServers": { "atlassian": { "url": "https://mcp.atlassian.com/v2/mcp" } } }
+```
+
+It shows as needing sign-in until you run `/mcp login atlassian` in a session
+or `hx mcp login atlassian` in a shell. That opens the browser, and the tools
+arrive as soon as you approve - no restart. HX follows the MCP authorization
+spec: it finds the authorization server from the server's metadata, registers
+itself as a client, signs in with PKCE, and keeps the token in `~/.hx/auth.json`
+(mode 0600), refreshing it before it expires and again if the server rejects
+it. Over SSH, paste the final redirect URL into the prompt instead.
+`/mcp logout atlassian` forgets it.
+
+A server that does not offer client registration needs a client you register
+with it yourself, and anything else about the sign-in can be pinned the same
+way:
+
+```json
+"oauth": { "clientId": "...", "clientSecret": "...", "scope": "read write", "callbackPort": 33418 }
+```
+
+To send a token of your own instead - an API key - give the server an
+`Authorization` header, and OAuth stays out of the way:
+`hx mcp add jira --url https://mcp.atlassian.com/v2/mcp --header "Authorization: Basic <base64 email:token>"`.
 
 **Hooks** are shell commands HX runs at named points in a turn. Four events:
 `PreToolUse`, `PostToolUse`, `UserPromptSubmit` and `Stop`.

{hx_cli-0.2.5 → hx_cli-0.2.6}/src/hx/__init__.py

@@ -1,5 +1,5 @@
 """HX - an agent harness for the terminal."""
 
-__version__ = "0.2.5"
+__version__ = "0.2.6"
 
 __all__ = ["__version__"]

{hx_cli-0.2.5 → hx_cli-0.2.6}/src/hx/cli.py

@@ -38,7 +38,8 @@ Usage:
   hx prompt                 Print the system prompt this directory would use
   hx trace [SESSION_ID] [PATH]
                             Write a session to a self-contained HTML trace
-  hx mcp list|add|remove    Manage MCP servers
+  hx mcp list|add|remove|login|logout
+                            Manage MCP servers, and sign in to remote ones
   hx auth [set|clear]       Show or change the OpenRouter API key
   hx docs [SECTION|--all]   Print the manual, or one section of it
   hx changelog [VERSION]    Print what shipped in each version
@@ -61,6 +62,14 @@ Options:
 DOC_COMMANDS = frozenset({"docs", "changelog"})
 """Commands that print a shipped document and exit, taking no run options."""
 
+VERBATIM_COMMANDS = DOC_COMMANDS | {"mcp", "auth"}
+"""Commands with flags of their own, so their arguments are taken as typed.
+
+`hx mcp add jira --url URL` and `hx mcp add fs npx -y server` are the
+documented forms; read as run options, `--url` and `-y` were refused as
+unknown before the command ever saw them.
+"""
+
 
 @dataclass(slots=True)
 class ParsedArgs:
@@ -76,6 +85,10 @@ class ParsedArgs:
 def main(argv: list[str] | None = None) -> int:
     """Parse arguments and dispatch. Returns a process exit code."""
     args = list(sys.argv[1:] if argv is None else argv)
+    if args and args[0] in VERBATIM_COMMANDS:
+        # `hx mcp add fs npx server --help` is a server's argument, not a
+        # request for HX's usage.
+        return _dispatch(args)
 
     if "--version" in args or "-V" in args:
         print(f"hx {__version__}")
@@ -114,10 +127,11 @@ def _dispatch(args: list[str]) -> int:
 
 
 def parse_args(args: list[str]) -> ParsedArgs:
-    # The documentation commands print and exit, so their arguments are taken
-    # verbatim: `hx docs --all` is a request for a section of the manual, not a
-    # run of HX with an unknown option.
-    if args and args[0] in DOC_COMMANDS:
+    # The documentation and management commands take their arguments verbatim:
+    # `hx docs --all` is a request for a section of the manual, and
+    # `hx mcp add jira --url URL` is for `hx mcp`, not a run of HX with an
+    # unknown option.
+    if args and args[0] in VERBATIM_COMMANDS:
         return ParsedArgs(command=args[0], rest=tuple(args[1:]))
 
     parsed = ParsedArgs()
@@ -250,6 +264,11 @@ class Runtime:
             return []
         statuses: list[Any] = await self.mcp.connect_all()
         await self.mcp.register_tools(self.tools)
+        for status in statuses:
+            if status.needs_login:
+                self.notices.append(
+                    f"MCP server {status.name} needs sign-in. Run /mcp login {status.name}."
+                )
         return statuses
 
     async def refresh_models_if_stale(self) -> None:
@@ -582,24 +601,31 @@ def run_tui_command(parsed: ParsedArgs) -> int:
     from hx.tui.app import run_tui
 
     try:
-        runtime = build_runtime(parsed, resume=_resume_target(parsed))
+        resume = _resume_target(parsed)
+        moved = _adopt_session_directory(parsed, resume)
+        runtime = build_runtime(parsed, resume=resume)
     except MissingCredential as exc:
         # Onboard for the route the configured model needs, not always for
         # OpenRouter: a user set to a Codex model wants a sign-in, not a key.
         if run_login(exc.provider_id) != 0:
             return _report(exc)
         try:
-            runtime = build_runtime(parsed, resume=_resume_target(parsed))
+            runtime = build_runtime(parsed, resume=resume)
         except Exception as retry_exc:
             return _report(retry_exc)
     except Exception as exc:
         return _report(exc)
+    if moved:
+        runtime.notices.append(moved)
+
+    relaunch: str | None = None
 
     async def main_async() -> None:
+        nonlocal relaunch
         try:
             await runtime.connect_mcp()
             await runtime.refresh_models_if_stale()
-            await run_tui(
+            relaunch = await run_tui(
                 runtime.loop,
                 runtime.bus,
                 runtime.settings,
@@ -619,12 +645,95 @@ def run_tui_command(parsed: ParsedArgs) -> int:
             await _rename_closed_session(runtime.loop)
         finally:
             runtime.bus.close()
-            await runtime.provider.aclose()
+            # Everything, not only the provider: a relaunch replaces this
+            # process, and an MCP server or background job left running would
+            # outlive the session that started it.
+            await runtime.aclose()
 
     asyncio.run(main_async())
+    if relaunch is not None:
+        _relaunch(relaunch)
     return 0
 
 
+def _adopt_session_directory(parsed: ParsedArgs, session_id: str | None) -> str | None:
+    """Run ``hx resume <id>`` in the directory the session was recorded in.
+
+    A session's paths, tool calls and permission grants all mean something in
+    its own directory; resumed against another one, the model edits files that
+    are not the ones it read. An explicit ``--cwd`` still wins.
+
+    Returns a notice when the recorded directory is gone and the session is
+    resumed here instead.
+    """
+    if session_id is None or parsed.cwd is not None:
+        return None
+    from hx.core.session import SessionNotFound, read_meta
+
+    try:
+        recorded = Path(read_meta(session_id).cwd)
+    except SessionNotFound:
+        return None  # build_runtime reports it
+    if recorded.is_dir():
+        parsed.cwd = recorded
+        return None
+    return f"This session was recorded in {recorded}, which no longer exists; resumed here."
+
+
+RUN_OPTIONS_WITH_VALUES = frozenset(
+    {"--model", "--mode", "--cwd", "--system-prompt", "--append-system-prompt", "--image"}
+)
+"""The run options that take the next argument as their value."""
+
+
+def relaunch_argv(argv: list[str], session_id: str) -> list[str]:
+    """The arguments to start HX again on ``session_id``.
+
+    The run's own options - ``--mode bypass``, ``--model`` - carry over, since
+    the user asked for them and nothing about switching sessions un-asks.
+    What picked the old session does not: the ``resume`` and its id, and a
+    ``--cwd``, which the new session's own directory replaces.
+    """
+    kept: list[str] = []
+    index = 0
+    while index < len(argv):
+        arg = argv[index]
+        if arg == "--cwd":
+            index += 2
+            continue
+        if arg in RUN_OPTIONS_WITH_VALUES:
+            kept += argv[index : index + 2]
+            index += 2
+            continue
+        if arg == "resume":
+            index += 1
+            if index < len(argv) and not argv[index].startswith("-"):
+                index += 1
+            continue
+        kept.append(arg)
+        index += 1
+    return [*kept, "resume", session_id]
+
+
+def _relaunch(session_id: str) -> None:
+    """Replace this process with HX resumed on ``session_id``.
+
+    ``exec`` rather than a child: the terminal, the pid and the shell's job
+    control stay exactly as they were, and there is no parent left waiting.
+
+    From the directory this process was started in, as if the user had typed
+    ``hx resume <id>`` there: that command moves into the session's own
+    directory by itself (:func:`_adopt_session_directory`), and the arguments
+    carried over - a script path, ``--system-prompt @p.md`` - were written
+    relative to here.
+    """
+    prefix = sys.orig_argv[: len(sys.orig_argv) - len(sys.argv) + 1]
+    command = [sys.executable, *prefix[1:], *relaunch_argv(sys.argv[1:], session_id)]
+    sys.stdout.flush()
+    sys.stderr.flush()
+    os.execv(sys.executable, command)
+
+
 RENAME_TIMEOUT_SECONDS = 10.0
 """A session name is not worth making the user wait for. Exit wins the tie."""
 
@@ -701,7 +810,13 @@ def run_print_command(parsed: ParsedArgs) -> int:
             )
         for status in await runtime.connect_mcp():
             if not status.connected:
-                print(f"[mcp] {status.name} unavailable: {status.error}", file=sys.stderr)
+                if status.needs_login:
+                    print(
+                        f"[mcp] {status.name} {status.error} - run `hx mcp login {status.name}`",
+                        file=sys.stderr,
+                    )
+                else:
+                    print(f"[mcp] {status.name} unavailable: {status.error}", file=sys.stderr)
         try:
             result = await runtime.loop.run(parsed.prompt, images)
             await _rename_closed_session(runtime.loop)
@@ -876,10 +991,14 @@ def _resume_target(parsed: ParsedArgs) -> str | None:
 MCP_USAGE = """\
 hx mcp list                                  Show configured servers
 hx mcp add NAME COMMAND [ARGS...]            Add a stdio server
-hx mcp add NAME --url URL                    Add an HTTP server
+hx mcp add NAME --url URL [--header K:V]...  Add an HTTP server
+hx mcp login NAME                            Sign in to an HTTP server in the browser
+hx mcp logout NAME                           Forget a server's sign-in
 hx mcp remove NAME                           Remove a server
 
 Add --user to write to ~/.hx/mcp.json instead of the project's .hx/mcp.json.
+An HTTP server that asks for sign-in gets it over OAuth unless a --header
+already sends Authorization.
 """
 
 
@@ -891,6 +1010,9 @@ def run_mcp_command(args: list[str]) -> int:
         save_config,
     )
 
+    if args and args[0] in {"--help", "-h", "help"}:
+        print(MCP_USAGE)
+        return 0
     user_level = "--user" in args
     args = [arg for arg in args if arg != "--user"]
     cwd = Path.cwd()
@@ -903,6 +1025,9 @@ def run_mcp_command(args: list[str]) -> int:
             return 0
         statuses = asyncio.run(_probe_servers(configs))
         for status in statuses:
+            if status.needs_login:
+                print(f"{status.name:<20} {status.error} - run `hx mcp login {status.name}`")
+                continue
             mark = "ok" if status.connected else "unavailable"
             detail = f" - {status.error}" if status.error else f" ({status.tool_count} tools)"
             print(f"{status.name:<20} {mark}{detail}")
@@ -914,7 +1039,12 @@ def run_mcp_command(args: list[str]) -> int:
             return 2
         name = args[1]
         if args[2] == "--url":
-            config = MCPServerConfig(name=name, transport="http", url=args[3])
+            try:
+                url, headers = _parse_http_add(args[3:])
+            except UsageError as exc:
+                print(f"error: {exc}\n\n{MCP_USAGE}", file=sys.stderr)
+                return 2
+            config = MCPServerConfig(name=name, transport="http", url=url, headers=headers)
         else:
             config = MCPServerConfig(
                 name=name, transport="stdio", command=args[2], args=tuple(args[3:])
@@ -922,6 +1052,16 @@ def run_mcp_command(args: list[str]) -> int:
         print(f"Added {name} to {save_config(config, cwd, user_level)}")
         return 0
 
+    if args[0] in {"login", "logout"}:
+        if len(args) < 2:
+            print(MCP_USAGE, file=sys.stderr)
+            return 2
+        server = next((c for c in load_configs(cwd) if c.name == args[1]), None)
+        if server is None:
+            print(f"No server named {args[1]}.", file=sys.stderr)
+            return 1
+        return _mcp_login(server) if args[0] == "login" else _mcp_logout(server)
+
     if args[0] == "remove":
         if len(args) < 2:
             print(MCP_USAGE, file=sys.stderr)
@@ -936,6 +1076,69 @@ def run_mcp_command(args: list[str]) -> int:
     return 2
 
 
+def _parse_http_add(rest: list[str]) -> tuple[str, dict[str, str]]:
+    """``URL [--header 'Name: value']...`` from ``hx mcp add NAME --url``."""
+    if not rest or rest[0].startswith("--"):
+        raise UsageError("--url needs a URL")
+    url, headers = rest[0], {}
+    tail = rest[1:]
+    while tail:
+        flag = tail.pop(0)
+        if flag not in {"--header", "-H"} or not tail:
+            raise UsageError(f"unexpected {flag!r}")
+        name, sep, value = tail.pop(0).partition(":")
+        if not sep or not name.strip():
+            raise UsageError("a header is written 'Name: value'")
+        headers[name.strip()] = value.strip()
+    return url, headers
+
+
+def _mcp_login(config: Any) -> int:
+    from hx.auth.oauth.browser import OAuthError
+    from hx.auth.oauth.callback import CallbackError
+    from hx.mcp.client import MCPError
+    from hx.mcp.manager import sign_in
+    from hx.mcp.oauth import SignInNotRequired
+
+    try:
+        asyncio.run(sign_in(config, ConsoleLogin()))
+    except SignInNotRequired as exc:
+        print(str(exc))
+        return 0
+    except (MCPError, OAuthError, CallbackError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nCancelled.", file=sys.stderr)
+        return 1
+
+    status = asyncio.run(_probe_servers([config]))[0]
+    if status.connected:
+        print(f"Signed in to {config.name}: {status.tool_count} tools available.")
+        return 0
+    print(f"Signed in, but {config.name} is still unavailable: {status.error}", file=sys.stderr)
+    return 1
+
+
+def _mcp_logout(config: Any) -> int:
+    from hx.auth.store import AuthStore
+    from hx.mcp.oauth import credential_id
+
+    if not config.url:
+        print(f"{config.name} is a local server; there is no sign-in to forget.")
+        return 0
+    if not config.uses_oauth:
+        # The stored sign-in is the server's, not this entry's: another
+        # project may reach the same server over OAuth and still need it.
+        print(f"{config.name} sends its own Authorization header; there is no sign-in to forget.")
+        return 0
+    if AuthStore().delete(credential_id(config.url)):
+        print(f"Signed out of {config.name}.")
+    else:
+        print(f"Not signed in to {config.name}.")
+    return 0
+
+
 async def _probe_servers(configs: list[Any]) -> list[Any]:
     from hx.mcp.manager import MCPManager
 
@@ -1093,6 +1296,9 @@ def run_auth_command(args: list[str]) -> int:
     from hx.providers import registry
 
     action = args[0] if args else "status"
+    if action in {"--help", "-h", "help"}:
+        print(AUTH_USAGE)
+        return 0
     resolver = AuthResolver()
 
     if action == "status":