feat(cli): add async server wait workflow

README.md

@@ -142,14 +142,14 @@ flowchart LR
     H --> B
 ```
 
-1MCP runs as an aggregated runtime behind `1mcp serve`. Static servers are prepared from startup configuration, template servers are materialized when client context is known, and the runtime can use async loading and lazy loading to reduce startup blocking and tool-surface noise. Instruction aggregation, presets, and notifications sit alongside that runtime rather than outside it.
+1MCP runs as an aggregated runtime behind `1mcp serve`. Static servers are prepared from startup configuration, template servers are materialized when client context is known, and the runtime can use async loading for early HTTP listener availability and lazy loading for a stable tool surface. Instruction aggregation, presets, and notifications sit alongside that runtime rather than outside it.
 
 ## Core Capabilities
 
 - Unified runtime for many MCP servers behind one `serve` process
 - CLI mode for progressive discovery with `1mcp instructions`, `1mcp inspect <server>`, `1mcp inspect <server>/<tool>`, and `1mcp run <server>/<tool> --args '<json>'`
 - Template servers for per-client or per-session resolution
-- Async loading and lazy loading for faster startup and narrower exposure
+- Opt-in async loading for early HTTP listener availability when clients can reconcile capability changes
 - Opt-in automatic recovery for owned stdio backends, with health/status visibility and operator restart controls
 - Instruction aggregation across static and template-backed servers
 - Presets, filters, and preset change notifications

docs/.vitepress/config/en.ts

@@ -194,6 +194,7 @@ function sidebar(): DefaultTheme.Sidebar {
           { text: 'instructions', link: '/commands/instructions' },
           { text: 'inspect', link: '/commands/inspect' },
           { text: 'run', link: '/commands/run' },
+          { text: 'wait', link: '/commands/wait' },
           { text: 'cli-setup', link: '/commands/cli-setup' },
           { text: 'auth', link: '/commands/auth' },
         ],

docs/.vitepress/config/zh.ts

@@ -204,6 +204,7 @@ function sidebar(): DefaultTheme.Sidebar {
           { text: 'instructions', link: '/zh/commands/instructions' },
           { text: 'inspect', link: '/zh/commands/inspect' },
           { text: 'run', link: '/zh/commands/run' },
+          { text: 'wait', link: '/zh/commands/wait' },
           { text: 'cli-setup', link: '/zh/commands/cli-setup' },
           { text: 'auth', link: '/zh/commands/auth' },
         ],

docs/en/commands/index.md

@@ -79,6 +79,7 @@ npx -y @1mcp/agent run context7/query-docs --args '{"libraryId":"/mongodb/docs",
 - **[instructions](/commands/instructions)** - Print the CLI playbook and current servers
 - **[inspect](/commands/inspect)** - Discover tools and inspect schemas
 - **[run](/commands/run)** - Execute a tool call
+- **[wait](/commands/wait)** - Wait for configured static servers to connect
 - **[cli-setup](/commands/cli-setup)** - Install Codex or Claude bootstrap files
 - **[auth](/commands/auth)** - Manage authentication profiles for secured servers
 

docs/en/commands/inspect.md

@@ -33,7 +33,7 @@ Depending on the target, `inspect` can:
 - List the exposed tools for a server when the target is `<server>`
 - Show a readable tool schema summary when the target is `<server>/<tool>`
 
-When supported, `inspect` uses the fast `/api/inspect` endpoint first and falls back to the MCP protocol when needed.
+When supported, `inspect` uses the authenticated `/api/v1/inspect` endpoint first and falls back to the MCP protocol when needed. It reports startup states for configured static servers before the first capability snapshot; use [`wait`](./wait.md) when a script must wait for `connected`.
 
 This is the command that turns the broad inventory from `instructions` into a scoped view. First inspect one server, then inspect one tool, and only then move to execution.
 

docs/en/commands/run.md

@@ -35,6 +35,8 @@ The `run` command is the execution step in the CLI workflow:
 
 `run` is intentionally the last step. The recommended flow is to discover broadly with `instructions`, narrow with `inspect`, confirm the exact tool schema with `inspect <server>/<tool>`, and only then invoke the tool.
 
+Before a REST-to-MCP fallback, `run` checks the client-facing inspect status. A loading backend returns `server_loading` and `1mcp wait <server>` rather than receiving an early MCP invocation. Failed or cancelled backends return `server_unavailable`; an OAuth-gated backend returns authorization guidance.
+
 ## Options
 
 ### Target and Discovery

docs/en/commands/wait.md

@@ -0,0 +1,29 @@
+---
+title: Wait Command - Wait for Static MCP Servers
+description: Wait for configured static MCP servers to become connected before invoking tools.
+---
+
+# Wait Command
+
+Wait for enabled configured static MCP servers to become connected through the authenticated `/api/v1/inspect` status contract.
+
+```bash
+npx -y @1mcp/agent wait [server] [options]
+```
+
+Without a server, `wait` covers all matching configured static servers. Templates and disabled servers are excluded. A template target returns `server_not_load_tracked`; an unknown target returns `server_not_found`.
+
+## Options
+
+- **`[server]`** - One configured static server to wait for
+- **`--timeout <ms>`** - Positive timeout in milliseconds, default `30000`
+- **`--url, -u <url>`** - Override the auto-detected runtime URL
+- **`--context <name>`** - Use a named Runtime Target Context
+- **`--preset`, `--tag-filter`, `--tags`** - Apply the same client-facing filters as `inspect`
+- **`--format <toon|text|json>`** - Select success output format
+
+## Behavior
+
+Success requires every requested server to report `connected` and `available`. `failed`, `cancelled`, `awaiting_oauth`, and unavailable terminal states stop immediately with a structured nonzero error. A timeout includes the last observed states and a recovery command. Waiting never cancels background loading.
+
+Use `wait` before `run` when a script must depend on a newly started backend. `run` also checks inspect status before its REST-to-MCP fallback and returns `server_loading` with the same recovery command when the backend is still loading.