docs(acp): document the async factory, drop the default model, add Zed setup

Review follow-ups on #143.

`MCPManager.create_stdio_server` existed with a one-line docstring that said
what it does and not why it has to exist: `create_from_server` is sync, and
called with a loop already running it offloads to a thread and blocks on the
result, stalling the caller's loop for the whole connect. A host serving over
that same loop — the ACP server on stdin/stdout — goes unresponsive while an
MCP server starts. `_create_tool_instance` was extracted without a docstring,
and the extraction dropped the comment explaining why refresh_ctx is stashed.
Both documented.

`--model` no longer defaults to a specific NVIDIA model. Baking a model choice
into the package is not the package's call; it is now required via the flag or
NOOA_MODEL, and the READMEs set it explicitly.

Added a Zed setup section, including the one thing that will otherwise waste
someone an afternoon: remote MCP servers authenticated inside Zed are invisible
to ACP agents (zed-industries/zed#54410).

Signed-off-by: Paul Furgale <pfurgale@nvidia.com>

Author: furgalep

README.md

@@ -203,6 +203,7 @@ its working directory:
 
 ```bash
 uv add nooa-acp
+export NOOA_MODEL=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
 export NVIDIA_API_KEY=nvapi-...
 
 # Agent command for the ACP client

packages/nooa-acp/README.md

@@ -13,16 +13,67 @@ Set the model and its provider credentials, then configure the client to launch
 this command with the repository as its working directory:
 
 ```bash
+export NOOA_MODEL=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
 export NVIDIA_API_KEY=nvapi-...
 uvx nooa-acp
 ```
 
+There is no default model. Pass `--model` or set `NOOA_MODEL`; the command
+exits with a usage error if neither is set.
+
 From this repository, use the workspace package as the client command:
 
 ```bash
 uv run --project "$PWD" --package nooa-acp -- nooa-acp
 ```
 
+## Configuring Zed
+
+Zed launches ACP agents as "external agents". Add NOOA to `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "NOOA": {
+      "type": "custom",
+      "command": "uvx",
+      "args": ["nooa-acp"],
+      "env": {
+        "NOOA_MODEL": "nvidia_nim/nvidia/nemotron-3-super-120b-a12b",
+        "NVIDIA_API_KEY": "nvapi-..."
+      }
+    }
+  }
+}
+```
+
+Pick NOOA from the `+` menu in the agent panel. Zed runs the command with the
+worktree as its working directory, so repository instructions and project
+sessions resolve against the open project.
+
+Credentials have to go in `env` here rather than Zed's own settings: the agent
+is a separate process and inherits only what Zed passes it. Use a secret
+manager wrapper as the `command` if you would rather not put a key in
+`settings.json`.
+
+### MCP servers do not carry over from Zed
+
+**Remote MCP servers you authenticated inside Zed are not usable from an ACP
+agent.** Zed holds those OAuth tokens itself and does not pass them down, so a
+server showing a green indicator in Zed's own UI arrives at the agent either
+with no tools at all or with nothing but its `authenticate` /
+`__complete_authentication` stubs. Local stdio MCP servers are unaffected.
+
+This is a known Zed limitation, tracked in
+[zed-industries/zed#54410](https://github.com/zed-industries/zed/issues/54410)
+(open, labelled `area:ai/mcp` + `area:ai/acp`). A maintainer has said the
+plumbing largely exists and the work is queued, but as of this writing it is
+unresolved.
+
+Configure the MCP server directly for NOOA instead — through NOOA's own
+`.mcp.json` — and it works normally, because the agent then owns the
+connection and its credentials rather than borrowing Zed's.
+
 ACP uses standard input and output for JSON-RPC. Diagnostics are written to
 standard error. The agent can execute generated Python and shell commands, so
 use an OS-level sandbox for untrusted tasks. Generated code shares the agent's

packages/nooa-acp/src/nooa_acp/cli.py

@@ -16,9 +16,8 @@
 @click.option(
     "--model",
     envvar="NOOA_MODEL",
-    default="nvidia_nim/nvidia/nemotron-3-super-120b-a12b",
-    show_default=True,
-    help="LiteLLM model name or configured NOOA model alias.",
+    required=True,
+    help="LiteLLM model name or configured NOOA model alias. Or set NOOA_MODEL.",
 )
 @click.option(
     "--client-type",

packages/nooa-acp/tests/test_cli.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+"""Model selection for the ACP entry point."""
+
+import click.testing
+import pytest
+from nooa_acp.cli import command
+
+
+@pytest.fixture
+def stubbed_serve(monkeypatch):
+    """Capture the llm_factory the command builds instead of serving."""
+    captured = {}
+
+    def fake_serve(llm_factory):
+        captured["llm_factory"] = llm_factory
+        return "coroutine-placeholder"
+
+    monkeypatch.setattr("nooa_acp.server.serve", fake_serve)
+    monkeypatch.setattr("nooa_acp.cli.asyncio.run", lambda coro: coro)
+    monkeypatch.setattr("nooa.secrets.load_secrets_into_env", lambda *a, **k: None)
+    return captured
+
+
+def test_model_is_required(monkeypatch):
+    monkeypatch.delenv("NOOA_MODEL", raising=False)
+
+    result = click.testing.CliRunner().invoke(command, [])
+
+    # No default model: the caller has to choose one.
+    assert result.exit_code == 2
+    assert "--model" in result.output
+
+
+def test_model_is_read_from_the_environment(monkeypatch, stubbed_serve):
+    monkeypatch.setenv("NOOA_MODEL", "openai/gpt-4o-mini")
+    requested = {}
+    monkeypatch.setattr(
+        "nooa.unifiedllm.get_llm_client",
+        lambda name, **kwargs: requested.setdefault("name", name),
+    )
+
+    result = click.testing.CliRunner().invoke(command, [])
+
+    assert result.exit_code == 0, result.output
+    stubbed_serve["llm_factory"]()
+    assert requested["name"] == "openai/gpt-4o-mini"
+
+
+def test_explicit_flag_overrides_the_environment(monkeypatch, stubbed_serve):
+    monkeypatch.setenv("NOOA_MODEL", "openai/gpt-4o-mini")
+    requested = {}
+    monkeypatch.setattr(
+        "nooa.unifiedllm.get_llm_client",
+        lambda name, **kwargs: requested.setdefault("name", name),
+    )
+
+    result = click.testing.CliRunner().invoke(command, ["--model", "anthropic/claude-sonnet-4-5"])
+
+    assert result.exit_code == 0, result.output
+    stubbed_serve["llm_factory"]()
+    assert requested["name"] == "anthropic/claude-sonnet-4-5"

packages/nooa-acp/tests/test_server.py

@@ -46,15 +46,19 @@ def test_acp_command_is_discovered_as_cli_plugin():
     assert dict(discover_commands())["acp"] is command
 
 
-def test_acp_command_defaults_to_public_nvidia_model():
+def test_acp_command_passes_the_nvidia_key_for_nvidia_models():
     runner = CliRunner()
     with (
         patch("nooa.secrets.load_secrets_into_env"),
         patch("nooa.unifiedllm.get_llm_client") as get_llm_client,
         patch("nooa_acp.server.serve") as serve,
         patch("nooa_acp.cli.asyncio.run"),
     ):
-        result = runner.invoke(command, env={"NVIDIA_API_KEY": "nvapi-test"})
+        result = runner.invoke(
+            command,
+            ["--model", "nvidia_nim/nvidia/nemotron-3-super-120b-a12b"],
+            env={"NVIDIA_API_KEY": "nvapi-test"},
+        )
 
     assert result.exit_code == 0
     llm_factory = serve.call_args.args[0]
@@ -66,6 +70,25 @@ def test_acp_command_defaults_to_public_nvidia_model():
     )
 
 
+def test_acp_command_leaves_the_key_alone_for_other_providers():
+    runner = CliRunner()
+    with (
+        patch("nooa.secrets.load_secrets_into_env"),
+        patch("nooa.unifiedllm.get_llm_client") as get_llm_client,
+        patch("nooa_acp.server.serve") as serve,
+        patch("nooa_acp.cli.asyncio.run"),
+    ):
+        result = runner.invoke(
+            command,
+            ["--model", "openai/gpt-4o-mini"],
+            env={"NVIDIA_API_KEY": "nvapi-test"},
+        )
+
+    assert result.exit_code == 0
+    serve.call_args.args[0]()
+    get_llm_client.assert_called_once_with("openai/gpt-4o-mini", client_type=None)
+
+
 class _MCPTools:
     async def lookup(self, query: str) -> str:
         """Look up a value in the test MCP server."""

packages/nooa-cli/README.md

@@ -27,6 +27,7 @@ run the NOOA coding agent from an ACP-compatible client:
 
 ```bash
 uv add nooa-acp
+export NOOA_MODEL=nvidia_nim/nvidia/nemotron-3-super-120b-a12b
 export NVIDIA_API_KEY=nvapi-...
 uv run nooa-acp
 ```

src/nooa/mcp/tool.py

@@ -698,6 +698,15 @@ def _create_tool_instance(
     tools_result: Any,
     refresh_ctx: dict[str, Any] | None = None,
 ) -> MCPTool:
+    """Build the dynamic per-server tool class from a completed ``list_tools``.
+
+    Shared by the sync and async factories: from here on the work is pure CPU
+    on an already-connected client, so it is identical either way.
+
+    ``refresh_ctx`` is stashed on the instance so ``_call_tool`` can
+    transparently refresh the OAuth token and retry once on a 401 mid-session —
+    cached access tokens can expire between connect and call.
+    """
     tool_specs = []
     for tool in tools_result.tools:
         input_schema = tool.inputSchema if isinstance(tool.inputSchema, dict) else {}
@@ -763,7 +772,30 @@ async def create_stdio_server(
         env: dict[str, str] | None = None,
         tool_call_timeout: timedelta = timedelta(seconds=60),
     ) -> MCPTool:
-        """Create an MCP tool from explicit stdio configuration without blocking the event loop."""
+        """Create an MCP tool from explicit stdio config, from inside an event loop.
+
+        :meth:`create_from_server` is synchronous. Called with a loop already
+        running, it hands the coroutine to a worker thread and blocks on the
+        result, which stalls the caller's loop for the whole connect and
+        ``list_tools`` round trip. A host that is itself serving over that loop
+        — the ACP server on stdin/stdout, for instance — goes unresponsive for
+        as long as the MCP server takes to start.
+
+        This awaits the connection in the caller's loop instead, so the host
+        keeps serving while an MCP server comes up. It covers stdio only: no
+        config file lookup and no OAuth, because neither applies to a local
+        subprocess. Use :meth:`create_from_server` for everything else.
+
+        Args:
+            server_name: Name for the generated tool class and its methods.
+            command: Executable to launch.
+            args: Arguments passed to ``command``.
+            env: Extra environment for the subprocess.
+            tool_call_timeout: Per-call timeout for the generated methods.
+
+        Returns:
+            An MCPTool instance with one method per tool on the server.
+        """
         client = create_mcp_client(
             transport="stdio",
             command=command,