Skip to content

docs: clarify stateful server limitations #254

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
haosenwang1018 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: clarify stateful server limitations #254

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -471,6 +471,8 @@ By default, the CLI uses **lazy-spawn connection pooling** to avoid repeated MCP
- **Stale detection**: Config changes trigger re-spawn
- **Fast fallback**: 5s spawn timeout, then direct connection

**Important limitation:** the daemon optimizes repeated startup cost, but `mcp-cli` commands are still **request-oriented**, not interactive sessions. This works well for stateless servers and one-off tool calls, but it is not a replacement for a persistent browser/session workflow.

**Control via environment:**
```bash
MCP_NO_DAEMON=1 mcp-cli info # Force fresh connection
Expand All @@ -482,6 +484,21 @@ MCP_DEBUG=1 mcp-cli info # See daemon debug output

When daemon is disabled (`MCP_NO_DAEMON=1`), the CLI uses a **lazy, on-demand connection strategy**. Server connections are only established when needed and closed immediately after use.

### Stateful server limitations

`mcp-cli` is best for **stateless MCP servers** or request/response-style tools. It is a poor fit for servers that expect one long-lived interactive session across multiple CLI invocations, such as:

- browser automation servers (`chrome-devtools-mcp`, Playwright MCP wrappers)
- servers with transaction/session semantics
- tools that keep important in-memory state between calls

Why this matters:
- each CLI command is still treated as its own operation boundary
- stdio servers may be started, reused briefly, or torn down independently of your intended workflow
- multi-step browser flows like “open page -> fill form -> click button -> screenshot” are not guaranteed to preserve the state model you expect across separate shell commands

If you need durable browser/session state, prefer a native MCP client or agent runtime that keeps a persistent session open instead of orchestrating the flow through separate `mcp-cli call ...` invocations.

```
┌─────────────────────────────────────────────────────────────────┐
│ USER REQUEST │
Expand Down