Proposal: Add session/tools_available notification for async MCP tool readiness

[ChinaLym]

Problem

When a client creates a session via session/new with mcpServers,
MCP tool connections are established asynchronously. The client has
no way to know when tools become available. If session/prompt is
sent before MCP tools are ready, the agent operates without tools,
leading to degraded responses.

Current Behavior

1. Client sends session/new with mcpServers: [...]
2. Agent returns sessionId immediately
3. Agent begins async MCP connection (tools/list, etc.)
4. Client sends session/prompt — tool_list may be empty
5. No notification exists for tool readiness

Proposed Solution

Add an agent → client notification:

​```jsonc
{
"method": "session/tools_available",
"params": {
"sessionId": "...",
"tools": [{ "name": "...", "description": "..." }],
"source": "mcp", // "mcp" | "builtin"
"serverName": "my-server" // which MCP server (optional)
}
}

---

Alternative: extend session/update

{
"method": "session/update",
  "params": {
  "sessionId": "...",
  "kind": "tools_changed",
  "tools": [...]
  }
}

---

Use Cases

Client can show a loading indicator until tools are ready
Client can queue the first prompt and send it only after tools load
Client can display which MCP tools are available in the UI
Handles partial readiness (some servers fast, some slow)

[jingchang0623-crypto]

This is a real production pain point.

[ChinaLym]

 已收到~感谢来信！

[jingchang0623-crypto]

This is a real production pain point. We run 5 agents with 15+ MCP servers on OpenClaw, and the async tool readiness gap causes silent failures constantly.

What We Hit in Production

Our cron-scheduled content agent starts at 01:00 AM. Session spawns, MCP servers begin connecting... but the agent receives its first prompt before filesystem MCP is ready. Result: the agent tries to write a file using a fallback path, creates a partial file, and the next agent picks it up and produces garbage.

We added a brutal but effective workaround: a 10-second hardcoded sleep after session creation. Is it elegant? No. Does it work? Mostly. But it adds 10 seconds of latency to every single task.

Why Your Proposal Matters

The session/tools_available notification solves this properly because it handles the partial readiness case — some MCP servers connect in 200ms, others take 3-5 seconds. A blanket timeout is wasteful; your approach lets clients react to actual readiness signals.

One Concern: Race Conditions

What happens if session/tools_available fires but the tool is actually still initializing? We have seen MCP servers return tools/list successfully but fail on the first actual tools/call. Maybe the notification should include a status: ready | initializing | error field?

The session/update Alternative

The session/update approach feels cleaner architecturally — fewer new message types to implement, and it can handle other session state changes too. But session/tools_available is more explicit and easier for client devs to understand.

I would lean toward session/update with a kind discriminator for future extensibility, but either works.

---

Documented our full MCP async pain journey: https://miaoquai.com/stories/mcp-protocol-practical-guide.html

[ChinaLym]

We're in the same boat — our current workaround is also a sleep-based delay after session/new to wait for MCP servers to connect. It works but is inherently wasteful and fragile: too short and tools are still missing; too long and it adds unnecessary latency to every session.Really like your suggestion about adding a status: ready | initializing | error field to the notification. This is an important nuance — tools/list returning successfully doesn't guarantee tools/call will work. A per-server status field would let clients:
Show precise loading states in the UI (e.g., "MCP server X: connecting...")
Distinguish between "still loading" and "permanently failed" servers
Make informed decisions about whether to proceed or wait
This aligns well with both the session/tools_available and session/update approaches.