First prompt after boot races async MCP tool registration — the model's first turn silently lacks every mcp__* tool

[jiaoqsh]

Summary

dsh-mcp-client registers its tools asynchronously after plugin activation, and
neither initialize nor any notification on the SDK JSON-RPC wire reflects when
that registration has settled. A session/prompt dispatched promptly after boot
therefore assembles its request tool schemas before tools/list completes: the
model's first turn sees only the built-in tools, with no error anywhere — it
simply behaves as if the MCP servers don't exist (in our case it started
exploring the environment with bash instead of calling the stock-data tool the
user expected).

Reproduction

Composition: the SDK server + agent spine + llm-deepseek + N
@deepseek-ai/dsh-mcp-client rows (streamable-http, local live servers that
answer initialize/tools/list normally). All packages 0.1.0-rc.6.

1. Spawn packaged-bin.js (plain Node), initialize, then session/prompt
   immediately — the standard SDK calling pattern.
2. Turn 1's request/header event lists only
   bash edit read skill todo_write write. No mcp__* tools. No error.
3. Send a second prompt to the same session: the request now lists the full
   mcp__<server>__<tool> set (33 tools in our composition).

Timing-dependent: we first integrated via a source-mode launch (tsx on a repo
checkout) where ~8s of TypeScript compilation masked the race — MCP clients
always won. Moving to the packaged runtime (~1s to first prompt) made the first
turn lose the race deterministically.

Why a consumer can't fix this cleanly

There is nothing to await or observe:

• initialize resolves before/independently of MCP discovery;
• the wire streams no MCP status (server startup status stays internal);
• tool registration is not a session event, so it can't be derived from the log.

Our current workaround is a blind, bounded sleep after spawn whenever the
composition carries MCP rows — it taxes every cold start and still guarantees
nothing under load.

Ask (any of these would do)

1. Gate initialize (or a dedicated request) on the composed MCP clients'
   initial discovery settling — bounded by the total-timeout proposal in Proposal: bound MCP connection and tool discovery with one total timeout #247 so
   an unresponsive server can't wedge boot; or
2. Notify: emit an MCP server status notification on the SDK wire (analogous
   to codex's mcpServer/startupStatus/updated), so clients can wait for
   terminal states; or
3. Query: a request that returns the current registered tool set / per-server
   discovery state.

Related: #247 (bounding connection + discovery with one total timeout — the
readiness signal is the consumer-visible half of the same lifecycle) and #314
(silent streamable-http failures — a readiness/status surface would have made
that diagnosable too).

Environment

@deepseek-ai/dsh-* 0.1.0-rc.6 (npm closure, packaged-bin.js under plain
Node 22.19 / 25), macOS 15. MCP servers: local streamable-http, responsive.

[kunwar-vp]

Reproduced independently with a stdio MCP server (~96 tools) via the Python SDK: the first run() after construction gets a session whose request/header tool list contains only the fs/todo tools; inserting a ~5s delay between client.start() and the first run() reliably makes the MCP tools appear. Same blind-sleep workaround as OP, same discomfort with it. The interaction with #1241 is what makes this dangerous: with no stderr diagnostics in the jsonrpc composition, the failure is completely silent — an unattended embedder gets a healthy-looking session that simply lacks its tools. Of OP's three proposals, gating initialize (or session/new) on initial activation seems strictly better than a status query, since no client has to remember to poll. Details of my repro in #2273.

[weijiafu14]

An immediately usable alternative is now available through pi2dsh + the unmodified pi-mcp-adapter package. This exact first-turn race is one of the bridge acceptance gates: every root Agent gets its own package runtime, and the awaited system-prompt/assemble plus tools/pre-execute waterfalls wait for session_start and refresh assembly.tools before the first request is sent.

dsh plugin --profile web add pi2dsh
dsh plugin --profile web add pi-mcp-adapter

The stock-stack E2E creates startup Agent A and /new Agent B, then makes a real DeepSeek MCP tool call on each; both first-turn tool/result events are present and isolated in their own DSH session logs. No blind startup sleep or core/surface fork is used.

This does not claim to fix the readiness seam in the official dsh-mcp-client; it provides a working ecosystem route that avoids the activation race today.

https://github.com/weijiafu14/pi2dsh/tree/main/examples/tui-mcp